Référence de codage

Cette page explique comment écrire des Custom Blocks pour AugeLab Studio Designer.

Les Custom Blocks sont des classes Python simples qui héritent de Block, définissent des sockets/composants dans init() et traitent les données dans run().

Démarrage rapide

• Commencez votre script par from studio.custom_block import * (obligatoire).

• Créez une classe qui hérite de Block.

• Définissez op_code avec le nom exact de la classe.

• Implémentez init() pour configurer les sockets et les composants UI.

• Implémentez run() pour lire les entrées et écrire les sorties.

• Enregistrez le bloc en bas avec add_block(...).

Info : Designer Window extrait le nom du bloc à partir de la première déclaration class MyBlock(Block): qu'il trouve, remplace les tabulations par 4 espaces, écrit <BlockName>.py, puis l'importe pour valider.

from studio.custom_block import *

try:
    import numpy as np
except ImportError:
    np = None


class Example_Block(Block):
    op_code = "Example_Block"  # Must match the class name

    def init(self) -> None:
        self.width = 200
        self.height = 150
        self.tooltip = "Adds a constant to the input image."

        # Socket names become keys for self.input[...] and self.output[...]
        self.input_sockets = [SocketTypes.ImageAny("Input Image")]
        self.output_sockets = [SocketTypes.ImageAny("Output Image")]

        # Components are stored by name in self.param
        self.param["Increment"] = TextInput(
            text="1",
            place_holder="integer",
            tool_tip="Value added to every pixel.",
        )

    def run(self) -> None:
        if np is None:
            return

        img = self.input["Input Image"].data
        inc = int(self.param["Increment"].value)
        self.output["Output Image"].data = img + inc


add_block(Example_Block.op_code, Example_Block)

.png) Example Custom Block

Phase d'amorçage

Importations obligatoires

Chaque script de Custom Block doit commencer par from studio.custom_block import *.

Cela fournit Block, SocketTypes, les composants Designer (TextInput, Slider, …) et add_block.

Importation de modules communautaires

Vous pouvez importer des packages tiers (NumPy, OpenCV, …) et les utiliser dans run().

Si vous installez des packages via la fenêtre Import Package, assurez-vous qu'ils fonctionnent sur toutes les plateformes cibles où votre scénario sera exécuté.

Avertissement : Tous les blocs fournis avec AugeLab Studio sont compatibles multiplateforme. L'installation ou l'importation de modules communautaires peut réduire la portabilité.

Définition de la classe

Le nom de la classe devient le nom du bloc affiché dans la liste Custom Blocks.

Vous pouvez ajouter des méthodes d'aide et de l'état interne selon les besoins.

Attributs & méthodes principaux

Block.op_code: str

Identifiant unique pour votre bloc.

Pour les blocs générés par Designer, op_code doit être identique au nom de la classe.

Info : Conserver op_code et les noms de sockets stables aide Studio à reconnecter les nœuds lorsque vous mettez à jour un bloc.

Block.tooltip: str

Texte d'infobulle affiché lorsque l'utilisateur survole le bloc.

.png) Tooltip shown on custom block

Block.init(self) -> None

Appelé lors de la création du bloc (drag-drop), duplication (copy/paste) ou chargement depuis un fichier de scénario.

Utilisez cette méthode pour configurer l'UI du bloc et les sockets :

• Définir input_sockets et output_sockets

• Créer des composants dans self.param (TextInput, DropDown, Slider, ...)

• Charger et enregistrer des chemins de ressources si nécessaire

Block.run(self) -> None

Exécuté à chaque étape du scénario.

Lisez depuis self.input, écrivez vers self.output, et (optionnellement) mettez à jour l'état des composants.

Sockets et flux de données

Block.input_sockets: list[SocketType]

Définit les entrées que le bloc accepte.

Chaque socket a un nom visible ; ce même nom devient la clé que vous utilisez dans self.input[...].

Constructeur de Socket

SomeSocketClass(SocketTypes.BaseSocketClass):
    def __init__(self, name: str = "", multiple: bool = False):
        """ 
        name: texte affiché à côté du graphisme du socket
        multiple: dessine une ligne horizontale pour indiquer un socket de type liste
        """
        ...

Types de sockets disponibles

Type de socket	Charge utile typique
ImageAny, ImageRGB, ImageGray	numpy.ndarray
Mask	numpy.ndarray
Integer	int
Number	int ou float
Boolean	bool
String	str
Generic	n'importe quel objet
Shape, Contour, Range, Pixel, Point	dépend du nœud en amont

Info : Les types exacts de charge utile dépendent du runtime et des nœuds en amont. Vous verrez souvent numpy.ndarray pour les images/masks et des primitives Python (int, float, bool, str) pour les sockets numériques/textuels.

Block.output_sockets: list[SocketType]

Même concept que pour les entrées : définissez les sorties puis écrivez les données par nom de socket en utilisant self.output["Name"].data = ....

Block.input: dict[str, object]

Carte d'exécution des noms de sockets d'entrée vers des objets qui portent la charge utile dans .data.

Chaque entrée suit aussi l'état de connexion via .is_connected. Si une entrée n'est pas connectée, .data vaut None.

class Example_Block(Block):
    def init(self) -> None:
        self.input_sockets = [
            SocketTypes.ImageAny("Image"),
            SocketTypes.Number("Constant"),
        ]

    def run(self) -> None:
        image = self.input["Image"].data
        constant = self.input["Constant"].data
        ...

Block.output: dict[str, object]

Carte d'exécution des noms de sockets de sortie vers des objets qui portent la charge utile dans .data.

class Example_Block(Block):
    def init(self) -> None:
        self.output_sockets = [
            SocketTypes.ImageAny("Result"),
            SocketTypes.Number("Detections"),
        ]

    def run(self) -> None:
        self.output["Result"].data = img_detections_drawn
        self.output["Detections"].data = n_detections

Composants (UI du bloc)

Block.param: dict[str, Component]

Les composants sont stockés dans self.param sous un nom unique de votre choix.

Utilisez-les pour configurer l'UI de votre bloc (champs texte, sliders, boutons, images, tableaux, etc.).

• Text Input

• Drop Down List

• Label

• Slider / Slider Labeled

• Check Box

• Button

• Image

• Table

(Référez-vous à components.md pour la liste complète et les détails.)

Chemins de ressources

Block.register_resource(name: str = "", path: str = "") -> str

Enregistre un chemin de fichier/dossier afin qu'il soit stocké avec le scénario et puisse être relocalisé avec le projet. Cela évite que des chemins absolus codés en dur cassent lorsque le scénario est déplacé sur un autre ordinateur.

Argument	Signification
name	Identifiant unique pour la ressource
path	Chemin du fichier/dossier à enregistrer

Retourne : str (le chemin enregistré)

Pour récupérer le chemin stocké plus tard, utilisez get_resource().

Exemple : laisser l'utilisateur choisir un fichier une fois

from studio.custom_block import *


class LoadImage(Block):
    op_code = "LoadImage"

    def init(self):
        self.width = 220
        self.height = 180

        self.output_sockets = [SocketTypes.ImageAny("Image")]

        self.param["Pick File"] = Button(text="Pick File")
        self.param["Pick File"].set_clicked_callback(self._pick_file)

    def _pick_file(self):
        path = QAFileDialog.getOpenFileName(
            caption="Choose an image",
            directory="",
            filter="Image Files (*.png *.jpg *.jpeg *.bmp)",
        )
        if path:
            self.register_resource("image_path", path)

    def run(self):
        path = self.get_resource("image_path")
        if not path:
            return
        # TODO: load the image from 'path' and set self.output["Image"].data


add_block(LoadImage.op_code, LoadImage)

Block.get_resource(name: str = "") -> str

Retourne le chemin enregistré pour un nom de ressource donné.

Dialogues de fichiers

QAFileDialog

Helper statique pour afficher des sélecteurs de fichier/dossier. Ces dialogues retournent un chemin choisi par l'utilisateur.

Info : Utilisez les file dialogs dans des callbacks (par ex. un clic sur Button), pas dans run().

QAFileDialog.getOpenFileName(**kwargs)

Argument	Signification
caption: str = ""	Titre du dialogue
directory: str = ""	Répertoire de départ
filter: str = ""	Filtre de fichiers, ex. "Image Files (*.png *.jpg *.bmp)"

Retourne : str (chemin du fichier sélectionné)

QAFileDialog.getExistingDirectory(**kwargs)

Argument	Signification
caption: str = ""	Titre du dialogue
directory: str = ""	Répertoire de départ

Retourne : str (chemin du dossier sélectionné)

Enregistrement

add_block(My_Block.op_code, My_Block)

Enregistre votre bloc pour qu'il apparaisse dans le Designer. Ceci est généralement généré pour vous par la Designer Window. Si vous le modifiez, gardez op_code et le nom de la classe cohérents.