Contrôle à distance#

Depuis un IDE#

DataLab peut être contrôlé à distance depuis un IDE (par exemple Spyder ou tout autre IDE, ou même un Jupyter Notebook) qui exécute un script Python. Il permet de se connecter à une instance de DataLab en cours d’exécution, d’ajouter un signal et une image, puis d’exécuter des calculs. Cette fonctionnalité est exposée par la classe RemoteProxy fournie dans le module cdl.proxy.

Depuis une application tierce#

DataLab peut également être contrôlé à distance depuis une application tierce, dans le même but.

Si l’application tierce est écrite en Python 3, elle peut directement utiliser la classe RemoteProxy comme mentionné ci-dessus. Depuis un autre langage, c’est également réalisable, mais cela nécessite d’implémenter un client XML-RPC dans ce langage en utilisant les mêmes méthodes de serveur proxy que dans la classe RemoteProxy.

Les données (signaux et images) peuvent également être échangées entre DataLab et l’application cliente distante, dans les deux sens.

L’application cliente distante peut être écrite dans n’importe quel langage qui prend en charge XML-RPC. Par exemple, il est possible d’écrire une application cliente distante en Python, Java, C++, C#, etc. L’application cliente distante peut être une application graphique ou une application en ligne de commande.

L’application cliente distante peut être exécutée sur le même ordinateur que DataLab ou sur un ordinateur différent. Dans ce dernier cas, l’application cliente distante doit connaître l’adresse IP de l’ordinateur exécutant DataLab.

L’application cliente distante peut être exécutée avant ou après DataLab. Dans ce dernier cas, l’application cliente distante doit essayer de se connecter à DataLab jusqu’à ce qu’elle réussisse.

Fonctionnalités prises en charge#

Les fonctionnalités prises en charge sont les suivantes :

• Basculer vers le panneau de signal ou d’image

• Supprimer tous les signaux et images

• Enregistrer la session en cours dans un fichier HDF5

• Ouvrir des fichiers HDF5 dans la session en cours

• Parcourir un fichier HDF5

• Ouvrir un signal ou une image à partir d’un fichier

• Ajouter un signal

• Ajouter une image

• Obtenir la liste des objets

• Exécuter un calcul avec des paramètres

Quelques exemples sont fournis pour aider à implémenter une telle communication entre votre application et DataLab :

• Voir le module : cdl.tests.remoteclient_app

• Voir le module : cdl.tests.remoteclient_unit

Exemples#

Lorsque vous utilisez Python 3, vous pouvez utiliser directement la classe RemoteProxy comme dans les exemples cités ci-dessus ou ci-dessous.

Voici un exemple en Python 3 d’un script qui se connecte à une instance de DataLab en cours d’exécution, ajoute un signal et une image, puis exécute des calculs (la structure de cellule du script le rend pratique à utiliser dans l’IDE Spyder):

"""
Example of remote control of DataLab current session,
from a Python script running outside DataLab (e.g. in Spyder)

Created on Fri May 12 12:28:56 2023

@author: p.raybaut
"""

# %% Importing necessary modules

# NumPy for numerical array computations:
import numpy as np

# DataLab remote control client:
from cdlclient import SimpleRemoteProxy as RemoteProxy

# %% Connecting to DataLab current session

proxy = RemoteProxy()

# %% Executing commands in DataLab (...)

z = np.random.rand(20, 20)
proxy.add_image("toto", z)

# %% Executing commands in DataLab (...)

proxy.toggle_auto_refresh(False)  # Turning off auto-refresh
x = np.array([1.0, 2.0, 3.0])
y = np.array([4.0, 5.0, -1.0])
proxy.add_signal("toto", x, y)

# %% Executing commands in DataLab (...)

proxy.compute_derivative()
proxy.toggle_auto_refresh(True)  # Turning on auto-refresh

# %% Executing commands in DataLab (...)

proxy.set_current_panel("image")

# %% Executing a lot of commands without refreshing DataLab

z = np.random.rand(400, 400)
proxy.add_image("foobar", z)
with proxy.context_no_refresh():
    for _idx in range(100):
        proxy.compute_fft()

Voici une réimplémentation de cette classe en Python 2.7 :

# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.

"""
DataLab remote controlling class for Python 2.7
"""

import io
import os
import os.path as osp
import socket
import sys

import ConfigParser as cp
import numpy as np
from guidata.userconfig import get_config_dir
from xmlrpclib import Binary, ServerProxy


def array_to_rpcbinary(data):
    """Convert NumPy array to XML-RPC Binary object, with shape and dtype"""
    dbytes = io.BytesIO()
    np.save(dbytes, data, allow_pickle=False)
    return Binary(dbytes.getvalue())


def get_cdl_xmlrpc_port():
    """Return DataLab current XML-RPC port"""
    if sys.platform == "win32" and "HOME" in os.environ:
        os.environ.pop("HOME")  # Avoid getting old WinPython settings dir
    fname = osp.join(get_config_dir(), ".DataLab", "DataLab.ini")
    ini = cp.ConfigParser()
    ini.read(fname)
    try:
        return ini.get("main", "rpc_server_port")
    except (cp.NoSectionError, cp.NoOptionError):
        raise ConnectionRefusedError("DataLab has not yet been executed")


class RemoteClient(object):
    """Object representing a proxy/client to DataLab XML-RPC server"""

    def __init__(self):
        self.port = None
        self.serverproxy = None

    def connect(self, port=None):
        """Connect to DataLab XML-RPC server"""
        if port is None:
            port = get_cdl_xmlrpc_port()
        self.port = port
        url = "http://127.0.0.1:" + port
        self.serverproxy = ServerProxy(url, allow_none=True)
        try:
            self.get_version()
        except socket.error:
            raise ConnectionRefusedError("DataLab is currently not running")

    def get_version(self):
        """Return DataLab public version"""
        return self.serverproxy.get_version()

    def close_application(self):
        """Close DataLab application"""
        self.serverproxy.close_application()

    def raise_window(self):
        """Raise DataLab window"""
        self.serverproxy.raise_window()

    def get_current_panel(self):
        """Return current panel"""
        return self.serverproxy.get_current_panel()

    def set_current_panel(self, panel):
        """Switch to panel"""
        self.serverproxy.set_current_panel(panel)

    def reset_all(self):
        """Reset all application data"""
        self.serverproxy.reset_all()

    def toggle_auto_refresh(self, state):
        """Toggle auto refresh state"""
        self.serverproxy.toggle_auto_refresh(state)

    def toggle_show_titles(self, state):
        """Toggle show titles state"""
        self.serverproxy.toggle_show_titles(state)

    def save_to_h5_file(self, filename):
        """Save to a DataLab HDF5 file"""
        self.serverproxy.save_to_h5_file(filename)

    def open_h5_files(self, h5files, import_all, reset_all):
        """Open a DataLab HDF5 file or import from any other HDF5 file"""
        self.serverproxy.open_h5_files(h5files, import_all, reset_all)

    def import_h5_file(self, filename, reset_all):
        """Open DataLab HDF5 browser to Import HDF5 file"""
        self.serverproxy.import_h5_file(filename, reset_all)

    def load_from_files(self, filenames):
        """Open objects from files in current panel (signals/images)"""
        self.serverproxy.load_from_files(filenames)

    def add_signal(
        self, title, xdata, ydata, xunit=None, yunit=None, xlabel=None, ylabel=None
    ):
        """Add signal data to DataLab"""
        xbinary = array_to_rpcbinary(xdata)
        ybinary = array_to_rpcbinary(ydata)
        p = self.serverproxy
        return p.add_signal(title, xbinary, ybinary, xunit, yunit, xlabel, ylabel)

    def add_image(
        self,
        title,
        data,
        xunit=None,
        yunit=None,
        zunit=None,
        xlabel=None,
        ylabel=None,
        zlabel=None,
    ):
        """Add image data to DataLab"""
        zbinary = array_to_rpcbinary(data)
        p = self.serverproxy
        return p.add_image(title, zbinary, xunit, yunit, zunit, xlabel, ylabel, zlabel)

    def get_object_titles(self, panel=None):
        """Get object (signal/image) list for current panel"""
        return self.serverproxy.get_object_titles(panel)

    def get_object(self, nb_id_title=None, panel=None):
        """Get object (signal/image) by number, id or title"""
        return self.serverproxy.get_object(nb_id_title, panel)

    def get_object_uuids(self, panel=None, group=None):
        """Get object (signal/image) list for current panel"""
        return self.serverproxy.get_object_uuids(panel, group)


def test_remote_client():
    """DataLab Remote Client test"""
    cdl = RemoteClient()
    cdl.connect()
    data = np.array([[3, 4, 5], [7, 8, 0]], dtype=np.uint16)
    cdl.add_image("toto", data)


if __name__ == "__main__":
    test_remote_client()

Boîte de dialogue de connexion#

Le package DataLab fournit également une boîte de dialogue de connexion qui peut être utilisée pour se connecter à une instance de DataLab en cours d’exécution. Elle est exposée par la classe cdl.widgets.connection.ConnectionDialog.

Exemple d’utilisation :

# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.

"""
DataLab Remote client connection dialog example
"""

# guitest: show,skip

from guidata.qthelpers import qt_app_context
from qtpy import QtWidgets as QW

from cdl.proxy import RemoteProxy
from cdl.widgets.connection import ConnectionDialog


def test_dialog():
    """Test connection dialog"""
    proxy = RemoteProxy(autoconnect=False)
    with qt_app_context():
        dlg = ConnectionDialog(proxy.connect)
        if dlg.exec():
            QW.QMessageBox.information(None, "Connection", "Successfully connected")
        else:
            QW.QMessageBox.critical(None, "Connection", "Connection failed")


if __name__ == "__main__":
    test_dialog()

API publique : client distant#

class cdl.core.remote.RemoteClient[source]#

Objet représentant un proxy/client vers le serveur XML-RPC de DataLab. Cet objet est utilisé pour appeler les fonctions de DataLab à partir d’un script Python.

Exemples

Voici un exemple simple de l’utilisation de RemoteClient dans un script Python ou dans un notebook Jupyter :

>>> from cdl.core.remote import RemoteClient
>>> proxy = RemoteClient()
>>> proxy.connect()
Connecting to DataLab XML-RPC server...OK (port: 28867)
>>> proxy.get_version()
'1.0.0'
>>> proxy.add_signal("toto", np.array([1., 2., 3.]), np.array([4., 5., -1.]))
True
>>> proxy.get_object_titles()
['toto']
>>> proxy["toto"]
<cdl.core.model.signal.SignalObj at 0x7f7f1c0b4a90>
>>> proxy[1]
<cdl.core.model.signal.SignalObj at 0x7f7f1c0b4a90>
>>> proxy[1].data
array([1., 2., 3.])

connect(port: str | None = None, timeout: float | None = None, retries: int | None = None) → None[source]#

Tentative de connexion au serveur XML-RPC de DataLab.

Paramètres:

• port – Port XML-RPC auquel se connecter. Si non spécifié, le port est automatiquement récupéré à partir de la configuration de DataLab.

• timeout – Délai d’attente en secondes. Par défaut, 5.0.

• retries – Nombre de tentatives. Par défaut, 10.

Lève:

• ConnectionRefusedError – Impossible de se connecter à DataLab

• ValueError – Délai d’attente non valide (doit être >= 0.0)

• ValueError – Nombre de tentatives non valide (doit être >= 1)

disconnect() → None[source]#

Déconnexion du serveur XML-RPC de DataLab.

is_connected() → bool[source]#

Renvoie True si connecté au serveur XML-RPC de DataLab.

get_method_list() → list[str][source]#

Renvoie la liste des méthodes disponibles.

add_signal(title: str, xdata: ndarray, ydata: ndarray, xunit: str | None = None, yunit: str | None = None, xlabel: str | None = None, ylabel: str | None = None) → bool[source]#

Ajouter des données de signal à DataLab.

Paramètres:

• title – Titre du signal

• xdata – Données X

• ydata – Données Y

• xunit – Unité X. Par défaut, None.

• yunit – Unité Y. Par défaut, None.

• xlabel – Libellé X. Par défaut, None.

• ylabel – Libellé Y. Par défaut, None.

Renvoie:

True si le signal a été ajouté avec succès, False sinon

Lève:

• ValueError – Type de données xdata non valide

• ValueError – Type de données ydata non valide

add_image(title: str, data: ndarray, xunit: str | None = None, yunit: str | None = None, zunit: str | None = None, xlabel: str | None = None, ylabel: str | None = None, zlabel: str | None = None) → bool[source]#

Ajouter des données d’image à DataLab.

Paramètres:

• title – Titre de l’image

• data – Données de l’image

• xunit – Unité X. Par défaut, None.

• yunit – Unité Y. Par défaut, None.

• zunit – Unité Z. Par défaut, None.

• xlabel – Libellé X. Par défaut, None.

• ylabel – Libellé Y. Par défaut, None.

• zlabel – Libellé Z. Par défaut, None.

Renvoie:

True si l’image a été ajoutée avec succès, False sinon

Lève:

ValueError – Type de données non valide

add_object(obj: SignalObj | ImageObj) → None[source]#

Ajouter un objet à DataLab.

Paramètres:

obj – Objet signal ou image

calc(name: str, param: DataSet | None = None) → None[source]#

Appeler la fonction de calcul name dans le processeur du panneau en cours.

Paramètres:

• name – Nom de la fonction de calcul

• param – Paramètre de la fonction de calcul. Par défaut, None.

Lève:

ValueError – unknown function

get_object(nb_id_title: int | str | None = None, panel: str | None = None) → SignalObj | ImageObj[source]#

Obtenir un objet (signal/image) à partir de l’index.

Paramètres:

• nb_id_title – Numéro d’objet, ou identifiant d’objet, ou titre d’objet. Par défaut, None (objet en cours).

• panel – Nom du panneau. Par défaut, None (panneau en cours).

Renvoie:

Objet

Lève:

KeyError – si l’objet n’est pas trouvé

get_object_shapes(nb_id_title: int | str | None = None, panel: str | None = None) → list[source]#

Obtenir les formes géométriques des éléments de tracé associés à l’objet (signal/image).

Paramètres:

• nb_id_title – Numéro d’objet, ou identifiant d’objet, ou titre d’objet. Par défaut, None (objet en cours).

• panel – Nom du panneau. Par défaut, None (panneau en cours).

Renvoie:

Liste des formes géométriques des éléments de tracé

add_annotations_from_items(items: list, refresh_plot: bool = True, panel: str | None = None) → None[source]#

Ajouter des annotations d’objet (éléments de tracé d’annotation).

Paramètres:

• items – éléments de tracé d’annotation

• refresh_plot – rafraîchir le tracé. Par défaut, True.

• panel – nom du panneau (valeurs valides : « signal », « image »). Si None, le panneau en cours est utilisé.

add_group(title: str, panel: str | None = None, select: bool = False) → None#

Add group to DataLab.

Paramètres:

• title – Group title

• panel – Panel name (valid values: « signal », « image »). Defaults to None.

• select – Select the group after creation. Defaults to False.

add_label_with_title(title: str | None = None, panel: str | None = None) → None#

Ajouter une étiquette avec le titre de l’objet sur le tracé associé

Paramètres:

• title – Titre de l’étiquette. Par défaut, None. Si None, le titre est le titre de l’objet.

• panel – nom du panneau (valeurs valides : « signal », « image »). Si None, le panneau en cours est utilisé.

close_application() → None#

Fermer l’application DataLab

context_no_refresh() → Generator[None, None, None]#

Renvoie un gestionnaire de contexte pour désactiver temporairement le rafraîchissement automatique.

Renvoie:

Gestionnaire de contexte

Exemple

>>> with proxy.context_no_refresh():
...     proxy.add_image("image1", data1)
...     proxy.compute_fft()
...     proxy.compute_wiener()
...     proxy.compute_ifft()
...     # Auto refresh is disabled during the above operations

delete_metadata(refresh_plot: bool = True, keep_roi: bool = False) → None#

Supprimer les métadonnées des objets sélectionnés

Paramètres:

• refresh_plot – Rafraîchir le tracé. Par défaut, True.

• keep_roi – Conserver la ROI. Par défaut, False.

get_current_panel() → str#

Renvoie le nom du panneau en cours.

Renvoie:

« signal », « image », « macro »))

Type renvoyé:

Panel name (valid values

get_group_titles_with_object_infos() → tuple[list[str], list[list[str]], list[list[str]]]#

Renvoie les titres des groupes et les listes des uuids et titres des objets internes.

Renvoie:

titres des groupes, listes des uuids et titres des objets internes

Type renvoyé:

Tuple

get_object_titles(panel: str | None = None) → list[str]#

Obtenir la liste des objets (signal/image) pour le panneau en cours. Les objets sont triés par numéro de groupe et index d’objet dans le groupe.

Paramètres:

panel – nom du panneau (valeurs valides : « signal », « image », « macro »). Si None, le panneau de données en cours est utilisé (c’est-à-dire le panneau de signal ou d’image).

Renvoie:

Liste des titres des objets

Lève:

ValueError – si le panneau n’est pas trouvé

get_object_uuids(panel: str | None = None, group: int | str | None = None) → list[str]#

Obtenir la liste des uuids des objets (signal/image) pour le panneau en cours. Les objets sont triés par numéro de groupe et index d’objet dans le groupe.

Paramètres:

• panel – nom du panneau (valeurs valides : « signal », « image »). Si None, le panneau en cours est utilisé.

• group – Group number, or group id, or group title. Defaults to None (all groups).

Renvoie:

Liste des uuid des objets

Lève:

ValueError – si le panneau n’est pas trouvé

classmethod get_public_methods() → list[str]#

Renvoie toutes les méthodes publiques de la classe, sauf elle-même.

Renvoie:

Liste des méthodes publiques

get_sel_object_uuids(include_groups: bool = False) → list[str]#

Renvoie les uuids des objets sélectionnés.

Paramètres:

include_groups – Si True, renvoie également les objets des groupes sélectionnés.

Renvoie:

Liste des uuids des objets sélectionnés.

get_version() → str#

Renvoie la version de DataLab.

Renvoie:

Version de DataLab

import_h5_file(filename: str, reset_all: bool | None = None) → None#

Ouvrir le navigateur HDF5 de DataLab pour importer un fichier HDF5.

Paramètres:

• filename – Nom du fichier HDF5

• reset_all – Réinitialiser toutes les données de l’application. Par défaut, None.

import_macro_from_file(filename: str) → None#

Importer une macro à partir d’un fichier

Paramètres:

filename – Nom du fichier.

load_from_directory(path: str) → None#

Open objects from directory in current panel (signals/images).

Paramètres:

path – directory path

load_from_files(filenames: list[str]) → None#

Ouvrir des objets à partir de fichiers dans le panneau en cours

Paramètres:

filenames – liste des noms de fichiers

open_h5_files(h5files: list[str] | None = None, import_all: bool | None = None, reset_all: bool | None = None) → None#

Ouvrir un fichier HDF5 de DataLab ou importer à partir de tout autre fichier HDF5.

Paramètres:

• h5files – Liste des fichiers HDF5 à ouvrir. Par défaut, None.

• import_all – Importer tous les objets à partir des fichiers HDF5. Par défaut, None.

• reset_all – Réinitialiser toutes les données de l’application. Par défaut, None.

raise_window() → None#

Faire apparaître la fenêtre de DataLab

reset_all() → None#

Réinitialiser toutes les données de l’application

run_macro(number_or_title: int | str | None = None) → None#

Exécute la macro.

Paramètres:

number_or_title – Numéro de macro, ou titre de macro. Par défaut, None (macro en cours).

Lève:

ValueError – si la macro n’est pas trouvée

save_to_h5_file(filename: str) → None#

Enregistrer dans un fichier HDF5 de DataLab.

Paramètres:

filename – Nom du fichier HDF5

select_groups(selection: list[int | str] | None = None, panel: str | None = None) → None#

Sélectionner des groupes dans le panneau en cours.

Paramètres:

• selection – Liste des numéros de groupe (1 à N), ou liste des uuids de groupe, ou None pour sélectionner tous les groupes. Par défaut, None.

• panel – nom du panneau (valeurs valides : « signal », « image »). Si None, le panneau en cours est utilisé. Par défaut, None.

select_objects(selection: list[int | str], panel: str | None = None) → None#

Sélectionner des objets dans le panneau en cours.

Paramètres:

• selection – Liste des numéros d’objet (1 à N) ou uuids à sélectionner

• panel – nom du panneau (valeurs valides : « signal », « image »). Si None, le panneau en cours est utilisé. Par défaut, None.

set_current_panel(panel: str) → None#

Basculer vers le panneau.

Paramètres:

panel – Nom du panneau (valeurs valides : « signal », « image », « macro »))

stop_macro(number_or_title: int | str | None = None) → None#

Arrête la macro.

Paramètres:

number_or_title – Numéro de macro, ou titre de macro. Par défaut, None (macro en cours).

Lève:

ValueError – si la macro n’est pas trouvée

toggle_auto_refresh(state: bool) → None#

Basculer l’état du rafraîchissement automatique.

Paramètres:

state – État du rafraîchissement automatique

toggle_show_titles(state: bool) → None#

Basculer l’état d’affichage des titres.

Paramètres:

state – État d’affichage des titres

API publique : méthodes supplémentaires#

Les méthodes de la classe de contrôle à distance (en utilisant le proxy ou le client distant) peuvent être complétées par des méthodes supplémentaires qui sont ajoutées dynamiquement à l’exécution. Ce mécanisme permet d’accéder aux méthodes des processeurs de DataLab (voir cdl.core.gui.processor).