Installation

OculiX runs as a pure Java application. The only thing you must install yourself is a recent JDK. Everything else — OpenCV, Tesseract, native helpers, OCR data — is bundled inside the JAR.

System requirements

Item	Minimum	Recommended
Operating system	Windows 10 · macOS 12 · Ubuntu 20.04 LTS	Latest stable
Java (JDK)	11	17 or 21 LTS
Architecture	x86-64	x86-64 (Apple Silicon supported via Rosetta and natively from v3.0.2)
RAM	1 GB free	4 GB free
Display	Any single screen	Multi-monitor supported

OculiX is tested on Eclipse Temurin and Azul Zulu — both free. Other certified OpenJDK builds (Liberica, Microsoft Build of OpenJDK, Amazon Corretto) also work.

java -version
# should print "openjdk version "11" / "17" / "21""

Option 1 — Run the IDE (most common)

Open the Releases page and download the latest oculixide-X.Y.Z.jar.
Double-click it, or run from a terminal:
Terminal window
```
java -jar oculixide-3.0.3.jar
```

The IDE opens with:

Workspace explorer on the left
Script editor in the center
Console at the bottom (live log + run output)
Modern Recorder accessible from the toolbar
Welcome tab on first launch with starter snippets

Open a script bundle (.sikuli folder), hit Run (▶), and OculiX takes over the screen.

Launch a script directly from the command line

# Open the IDE on a specific script
java -jar oculixide-3.0.3.jar -l my-script.sikuli

# Open AND run immediately (great for cron / scheduled tasks)
java -jar oculixide-3.0.3.jar -l my-script.sikuli -e

Cross-platform — works on Linux, macOS, Windows (including WSL).

Option 2 — Use OculiX as a Java library

OculiX is published on Maven Central under io.github.oculix-org:

<dependency>
    <groupId>io.github.oculix-org</groupId>
    <artifactId>oculixapi</artifactId>
    <version>3.0.3</version>
</dependency>

Gradle:

implementation("io.github.oculix-org:oculixapi:3.0.3")

If your project also calls OpenCV directly, add the Apertix binary OculiX was built against:

<dependency>
  <groupId>io.github.julienmerconsulting.apertix</groupId>
  <artifactId>opencv</artifactId>
  <version>4.10.0-0</version>
</dependency>

Apertix is a custom JNA-based build of OpenCV 4.10.0 that avoids the classic System.loadLibrary conflicts you hit when mixing OpenCV with other native libraries on Windows.

Option 3 — Build from source

git clone https://github.com/oculix-org/Oculix.git
cd Oculix
mvn clean install -DskipTests

The Maven build produces:

Module	Artifact
`API/`	`oculixapi-<version>.jar`
`IDE/`	`oculixide-<version>.jar`
`MCP/`	`oculix-mcp-server-<version>.jar`
`Reporter/`	`oculix-reporter-<version>.jar`
`Additional-Wrappers/`	language wrapper modules

Profile-driven fat-jars are generated by the make-API and make-IDE Maven profiles. IntelliJ IDEA run configurations are checked in under .idea/runConfigurations/ so you can launch the IDE in dev mode straight from the project window.

Platform-specific notes

Windows

All native helpers (WinUtil.dll, OpenCV JNA binaries) are inside the JAR. No PATH setup, no MSVC runtime install, nothing.
Multi-monitor: OculiX detects each Screen(n) via the standard AWT graphics environment.
High DPI: scripts capture and replay at the OS coordinate system. If you record on 100 % scaling and run on 150 %, similarity may drop — use Pattern("foo.png").similar(0.7f) to widen the matcher.

macOS

Apple Silicon (M1/M2/M3) supported natively from OculiX 3.0.2.
On first launch, macOS asks for Accessibility and Screen Recording permissions for the Java runtime. Grant both in System Settings → Privacy & Security — without them, OculiX cannot move the mouse or capture the screen.
The MacUtil.m native helper handles native AppleScript bridges and window inspection.

Linux

Tested on Ubuntu 20.04 / 22.04 / 24.04, Debian 12, Fedora 40, Arch.
X11 fully supported. Wayland works through XWayland — direct Wayland support is on the roadmap.
Headless servers (CI runners): use the server runner mode for headless execution. See the CLI reference.
LinuxSupport.java handles Linux-specific window listing, focus, and clipboard quirks.

Optional — PaddleOCR HTTP server

Tesseract is embedded and good enough for Latin scripts. For high-accuracy CJK or complex layouts, install the optional paddleocrserver-powered:

pip install paddleocrserver-powered
paddleocrserver
# Listens on http://localhost:5000

OculiX’s PaddleOCREngine automatically discovers a running server on localhost:5000. No configuration needed.

Verify the install

The fastest smoke test from the IDE:

from sikuli import *
popup("OculiX is running. Java: " + getJavaVersion())

From a Java project:

import org.sikuli.script.Screen;

public class Smoke {
  public static void main(String[] args) {
    Screen s = new Screen();
    System.out.println("Primary screen: " + s.getW() + "x" + s.getH());
  }
}

Now you’re ready to write your first script.