Référence API

Cette page est un index navigable de l’API OculiX. Pour les signatures de méthodes complètes et le détail des paramètres, la Javadoc auto-générée fait foi.

Javadoc complète — oculixapi Auto-générée à chaque release Maven Central, source de vérité pour les signatures, noms de paramètres et types de retour.

L’organisation des packages reprend celle de SikuliX, pour que les scripts existants continuent de fonctionner sans modification. La plupart des utilisateurs n’ont besoin que d’une poignée de classes dans org.sikuli.script.

Cœur — matching visuel

Screen

Un écran physique. Screen(0) est le principal. Hérite de Region. Multi-écran via Screen(n).

Region

Une zone rectangulaire dans laquelle on cherche. C’est là que vivent find, click, type.

Pattern

Une image accompagnée de ses réglages — similar(), targetOffset().

Match

Un find réussi : une Region enrichie d’un score et du Pattern qui l’a produit.

Location

Un point (x, y) unique.

Settings

Configuration statique du moteur — MinSimilarity, WaitScanRate, AutoWaitTimeout, etc.

Quelques classes complémentaires fréquemment utilisées :

Classe	Rôle
`Image`	Une image capturée ou chargée, découplée du disque.
`ScreenImage`	Une `BufferedImage` plus sa region d’origine — ce que retourne `capture()`.
`Finder`	Wrapper OpenCV bas niveau. `findFeatures()` vit ici.
`FindFailed`	Exception levée quand aucun match n’atteint le seuil de similarité.
`ImageMissing`	Exception levée quand un fichier image référencé n’est pas sur le disque.

Region — la classe centrale

Les cinq verbes de matching :

Match  find(Object target);                  // lève FindFailed si rien
Match  exists(Object target);                // renvoie null si rien
Match  exists(Object target, double timeout);
Match  wait(Object target, double timeout);
boolean waitVanish(Object target, double timeout);
Iterator<Match> findAll(Object target);

Les verbes d’action — chacun retourne la cible sur laquelle il a agi, pour permettre le chaînage :

int click(Object target);
int doubleClick(Object target);
int rightClick(Object target);
int hover(Object target);
int type(String text);
int type(Object target, String text);        // clique d'abord, puis frappe
int paste(String text);
int dragDrop(Object from, Object to);
int mouseDown(int buttons);
int mouseUp(int buttons);
int wheel(int direction, int steps);
int keyDown(String keys);
int keyUp(String keys);

Les opérations de sous-region — toutes retournent une nouvelle Region :

Region above(int n);
Region below(int n);
Region left(int n);
Region right(int n);
Region inside();
Region nearby(int n);
Region grow(int width, int height);
Region morphTo(Region other);

Pattern — affiner le matching

Pattern p = new Pattern("button.png")
    .similar(0.85)            // seuil de similarité par appel
    .targetOffset(20, 5);     // clic 20 px à droite, 5 px sous le centre

Screen — accès aux moniteurs

Screen.getNumberScreens();    // combien de moniteurs détectés
Screen s = new Screen(0);     // principal
Screen s = new Screen(1);     // secondaire
s.capture();                  // ScreenImage de tout l'écran
s.capture(region);            // ScreenImage d'une sous-region

OCR — texte à l’écran

TextRecognizer

Front-end Tesseract embarqué. Utilisé en interne par Region.text().

PaddleOCREngine

Client HTTP du serveur PaddleOCR local (localhost:5000). Pour CJK et mises en page complexes.

PaddleOCRClient

Transport bas niveau. La plupart des utilisateurs passent par PaddleOCREngine.

String all = region.text();
Match label = region.findText("Submit");

PaddleOCREngine ocr = new PaddleOCREngine();
String json = ocr.recognize(screenImage.getFile());
int[] xywh = ocr.findTextCoordinates(json, "Submit");
Map<String, Double> results = ocr.parseTextWithConfidence(json);

Voir le guide OCR pour le détail complet.

Écrans distants — VNC

VNCScreen

Un Screen adossé à un serveur VNC distant. Même API que Screen local.

VNCRobot

Injection bas niveau d’événements d’entrée via VNC.

VNCClient

Le client brut du protocole VNC.

VNCFrameBuffer

Buffer de pixels décodé de l’écran distant.

VNCClipboard

Synchronisation bidirectionnelle du presse-papier.

XKeySym

2200+ définitions de symboles de touche X11.

VNCScreen vnc = VNCScreen.start("192.168.1.10", 5900, "password", 1920, 1080);
vnc.click("button.png");
vnc.type("hello");
vnc.stop();

Android — ADB

ADBScreen

Un Screen adossé à un appareil Android via ADB.

ADBDevice

Contrôle direct de l’appareil — tap, swipe, key, shell.

ADBClient

Client bas niveau du protocole ADB. jadb embarqué — pas besoin du binaire adb installé.

ADBRobot

Injection d’événements d’entrée pour scénarios avancés.

ADBScreen android = ADBScreen.start("/path/to/adb");
android.click("button.png");
android.getDevice().tap(540, 1200);

Testé sur Android 12+ via USB et WiFi (pairing ADB).

SSH

Classe	Rôle
`SSHTunnel`	Ouvrir un tunnel SSH depuis Java. `jcraft/jsch` embarqué, aucune dépendance externe.

SSHTunnel tunnel = new SSHTunnel("user", "remote-host", 22, "password");
tunnel.open(5900, "localhost", 5900);  // local 5900 → distant localhost:5900
VNCScreen vnc = VNCScreen.start("localhost", 5900, "", 1920, 1080);

Runners de scripting

JythonRunner

Python 2.7 sur la JVM — l’option historique, le plus de doc disponible.

JRubyRunner

JRuby sur la JVM, syntaxe Ruby, même surface d’API.

PythonRunner

CPython 3 via sous-processus. Voir aussi Operix pour la session py4j persistante.

PowerShellRunner

PowerShell, Windows. Pour les pipelines AD / Exchange / SCCM.

AppleScriptRunner

AppleScript, macOS. Pour Automator et Shortcuts.

RobotFrameworkRunner

Bibliothèque de keywords Robot Framework — pour les équipes QA déjà sur Robot.

NetworkRunner

Exécution distribuée à distance — un plan de contrôle, plusieurs agents.

ServerRunner

Serveur HTTP headless pour la CI. Reçoit les scripts via API REST.

Voir le guide des langages de scripting.

IDE et workspace

Classe	Rôle
`SikulixIDE`	Point d’entrée de l’IDE.
`ScriptExplorer`	Le panneau d’exploration du workspace.
`WelcomeTab`	Onglet d’accueil au premier lancement.
`EditorTabPane`	L’éditeur de script avec miniatures d’images.
`ConsolePanel`	La console du bas.
`RecorderAssistant`	Moteur du Modern Recorder.

Les utilisateurs finaux n’y touchent normalement pas. Ces classes sont publiques pour que les auteurs de plugins puissent étendre l’IDE.

Serveur MCP — Model Context Protocol

oculix-mcp-server est un module Maven séparé qui expose OculiX comme un serveur MCP (transport stdio + HTTP). Il signe chaque action avec Ed25519 et écrit un journal d’audit JSONL chaîné en SHA-256, conçu pour les environnements régulés.

<dependency>
  <groupId>io.github.oculix-org</groupId>
  <artifactId>oculix-mcp-server</artifactId>
  <version>3.0.4-rc1</version>
</dependency>

Outil exposé via MCP	Correspond à
`Click`	`Region.click()`
`DblClick`	`Region.doubleClick()`
`RClick`	`Region.rightClick()`
`Find`	`Region.find()`
`FindText`	`Region.findText()`
`Exists`	`Region.exists()`
`Wait`	`Region.wait()`
`KeyCombo`	Événement clavier synthétique
`OCR`	`Region.text()` / `PaddleOCREngine.recognize()`
`Screenshot`	`Screen.capture()`
`Type`	`Region.type()`

Utilitaires

Commons

Helpers partagés — résolution de chemins, checks de version, bootstrap OCR.

Debug

Façade de logging — Debug.log(), Debug.error(), Debug.info().

RunTime

Introspection runtime — OS, version Java, statut fat-jar.

FileManager

Opérations fichier multi-plateforme utilisées par l’IDE.

XKeySym

Définitions de keysyms X11 pour VNC.

SikuliXception

Exception checked à l’échelle du projet.

Pour aller plus loin

Javadoc complète sur javadoc.io Signatures détaillées, paramètres, exceptions levées, héritage AWT/Swing complet.

Référence CLI Exécuter des scripts sans l'IDE, options du server runner, variables d'environnement.

Migration depuis SikuliX Pour les scripts existants — ce qui change, ce qui ne change pas.

Guides utilisateur Visual matching, OCR, pipeline de vision, langages de scripting.