sikuli-go (Python)

This directory contains the Python client for sikuli-go with Sikuli-style Screen + Pattern APIs.

Canonical Documentation

Long-form Python docs now live in the published guide:

• Python Client
• Installation
• First Script
• Runtime
• Troubleshooting
• Getting Help

Quickstart

init:py-examples prompts for the target directory, creates requirements.txt, installs into .venv, and copies examples. Each example bootstraps sikuli-go into ./.sikuli-go/bin and prepends it to PATH for the process. The published package name is sikuli-go; the import module remains sikuligo.

pipx run sikuli-go init:py-examples
cd sikuli-go-demo
python3 examples/click.py

runs:

from __future__ import annotations
from sikuligo import Pattern, Screen

screen = Screen()
try:
    match = screen.click(Pattern("assets/pattern.png").exact())
    print(f"clicked match target at ({match.target_x}, {match.target_y})")
finally:
    screen.close()

Install Into An Existing Environment

If you manage your own environment instead of using the scaffold:

python -m pip install sikuli-go

Package name vs import name:

• install: sikuli-go
• import: sikuligo

Runtime Helpers

Install the runtime binaries on PATH:

pipx run sikuli-go install-binary

Start the runtime and dashboard:

pipx run sikuli-go -listen

Open:

• http://127.0.0.1:8080/dashboard

Run the standalone monitor after installing the binaries:

sikuli-go-monitor

By default it serves the monitor UI on :8080 and reads sikuli-go.db from the current working directory.

Dashboard Preview

The local runtime exposes both the dashboard and the standalone monitor workflow described in the guide:

• Dashboard Guide

Common Package Entry Points

• Screen() or Screen.start() uses auto mode
• Screen.connect() attaches to an existing runtime
• Screen.spawn() forces a new runtime process
• screen.region(x, y, w, h) scopes the search area

For the full runtime model, environment inputs, and troubleshooting notes, use the Python guide pages above.

FindOnScreen Benchmark Test Results

Generated: 2026-03-07T23:32:15.506029+00:00

Reports

• Markdown Summary
• JSON Report
• Raw go test Output
• Performance SVG
• Accuracy SVG
• Scenario Kind Match Time SVG
• Scenario Kind Success SVG
• Resolution Match Time SVG
• Resolution Matches SVG
• Resolution Misses SVG
• Resolution False Positives SVG

Engine Summary

Cases/OK metrics are query-level counts (regions x scenarios x resolutions), not just benchmark row count.

Engine	Cases	OK	Partial	Not Found	Unsupported	Error	Overlap Miss	Avg ms/op	Median ms/op
akaze	120	39	0	78	0	0	3	172.121	147.695
brisk	120	47	0	63	0	0	10	388.483	123.118
hybrid	120	69	0	45	0	0	6	171.017	134.411
kaze	120	63	0	50	0	0	7	824.898	640.512
orb	120	13	0	96	0	0	11	56.443	44.794
sift	120	56	0	55	0	0	9	256.756	198.264
template	120	64	0	56	0	0	0	154.257	114.466

Run Mega Summary

• Open run mega summary image

Benchmark Graphs

• Open performance graph

• Open accuracy graph

Scenario Kind Graphs

• Open scenario kind match time graph

• Open scenario kind success graph

Resolution Group Graphs

• Open resolution match time graph

• Open resolution matches graph

• Open resolution misses graph

• Open resolution false positives graph

Artifact Directories

• Visual Root
• Scenario Summaries

Scenario Summary Images (10)

hybrid_gate_conflicts_1920x1080_i09

• Open hybrid_gate_conflicts_1920x1080_i09 image

multi_monitor_dpi_shift_1920x1080_i10

• Open multi_monitor_dpi_shift_1920x1080_i10 image

noise_stress_random_1920x1080_i04

• Open noise_stress_random_1920x1080_i04 image

orb_feature_rich_1920x1080_i07

• Open orb_feature_rich_1920x1080_i07 image

perspective_skew_sweep_1920x1080_i06

• Open perspective_skew_sweep_1920x1080_i06 image

photo_clutter_1920x1080_i02

• Open photo_clutter_1920x1080_i02 image

repetitive_grid_camouflage_1920x1080_i03

• Open repetitive_grid_camouflage_1920x1080_i03 image

scale_rotate_sweep_1920x1080_i05

• Open scale_rotate_sweep_1920x1080_i05 image

template_control_exact_1920x1080_i08

• Open template_control_exact_1920x1080_i08 image

vector_ui_baseline_1920x1080_i01

• Open vector_ui_baseline_1920x1080_i01 image