API: pkg/sikuli

package sikuli // import "github.com/smysnk/sikuligo/pkg/sikuli"

Package sikuli provides the compatibility-facing automation API used by
sikuli-go.

The surface is intentionally aligned with common SikuliX concepts so existing
script flows can migrate with minimal rewriting:
  - Pattern and similarity tuning
  - Region scoped search and wait semantics
  - Screen level orchestration
  - Input control (click, type, hotkey)
  - OCR and observe events

Java SikuliX and sikuli-go are not byte-for-byte identical, but the exported
contracts in this package are designed to preserve the same mental model.

CONSTANTS

const (
	// DefaultSimilarity matches classic Sikuli behavior for image search.
	DefaultSimilarity = 0.70

	// ExactSimilarity is used by Pattern.Exact().
	ExactSimilarity = 0.99

	// DefaultAutoWaitTimeout is the baseline timeout for wait/find loops.
	DefaultAutoWaitTimeout = 3.0

	// DefaultWaitScanRate controls wait polling frequency.
	DefaultWaitScanRate = 3.0

	// DefaultObserveScanRate controls observe polling frequency.
	DefaultObserveScanRate = 3.0
)
const DefaultOCRLanguage = "eng"

VARIABLES

var (
	ErrFindFailed         = errors.New("sikuli: find failed")
	ErrTimeout            = errors.New("sikuli: timeout")
	ErrInvalidTarget      = errors.New("sikuli: invalid target")
	ErrBackendUnsupported = errors.New("sikuli: backend unsupported")
	ErrRuntimeUnavailable = errors.New("sikuli: live runtime unavailable")
)

FUNCTIONS

func SearchWaitVanish(probe SearchProbe, timeout, interval time.Duration) (bool, error)
    SearchWaitVanish applies the canonical vanish contract to a search probe.
    It returns true when the target is absent and false on timeout.

func SortMatchesByColumnRow(matches []Match)
    SortMatchesByColumnRow keeps parity with Java helper behavior for "by
    column".

func SortMatchesByRowColumn(matches []Match)
    SortMatchesByRowColumn keeps parity with Java helper behavior for "by row".


TYPES

type AppAPI interface {
	Open(name string, args []string, opts AppOptions) error
	Focus(name string, opts AppOptions) error
	Close(name string, opts AppOptions) error
	IsRunning(name string, opts AppOptions) (bool, error)
	ListWindows(name string, opts AppOptions) ([]Window, error)
	FindWindows(name string, query WindowQuery, opts AppOptions) ([]Window, error)
	GetWindow(name string, query WindowQuery, opts AppOptions) (Window, bool, error)
	FocusedWindow(name string, opts AppOptions) (Window, bool, error)
}
    AppAPI exposes lightweight app lifecycle helpers used by script flows.

type AppController struct {
	// Has unexported fields.
}

func NewAppController() *AppController

func (c *AppController) Close(name string, opts AppOptions) error

func (c *AppController) FindWindows(name string, query WindowQuery, opts AppOptions) ([]Window, error)

func (c *AppController) Focus(name string, opts AppOptions) error

func (c *AppController) FocusedWindow(name string, opts AppOptions) (Window, bool, error)

func (c *AppController) GetWindow(name string, query WindowQuery, opts AppOptions) (Window, bool, error)

func (c *AppController) IsRunning(name string, opts AppOptions) (bool, error)

func (c *AppController) ListWindows(name string, opts AppOptions) ([]Window, error)

func (c *AppController) Open(name string, args []string, opts AppOptions) error

func (c *AppController) SetBackend(backend core.App)

type AppOptions struct {
	Timeout time.Duration
}

type Finder struct {
	// Has unexported fields.
}

func NewFinder(source *Image) (*Finder, error)
    NewFinder creates a search/OCR helper bound to a source image.

func (f *Finder) CollectLines(params OCRParams) ([]OCRLine, error)
    CollectLines runs OCR and groups word-level geometry into line-level
    results.

func (f *Finder) CollectWords(params OCRParams) ([]OCRWord, error)
    CollectWords runs OCR and returns word-level geometry for the source image.

func (f *Finder) Count(pattern *Pattern) (int, error)
    Count returns the number of matches for the given pattern.

func (f *Finder) Destroy()
    Destroy clears the compatibility iterator state and last-match cache.

func (f *Finder) Exists(pattern *Pattern) (Match, bool, error)
    Exists returns the first match when present. Missing targets return
    (Match{}, false, nil).

func (f *Finder) Find(pattern *Pattern) (Match, error)
    Find returns the best match for the pattern.

func (f *Finder) FindAll(pattern *Pattern) ([]Match, error)
    FindAll returns all candidate matches for the pattern.

func (f *Finder) FindAllByColumn(pattern *Pattern) ([]Match, error)
    FindAllByColumn returns all matches sorted left-to-right then top-to-bottom.

func (f *Finder) FindAllByRow(pattern *Pattern) ([]Match, error)

func (f *Finder) FindAnyList(patterns []*Pattern) ([]Match, error)

func (f *Finder) FindBestList(patterns []*Pattern) (Match, error)

func (f *Finder) FindText(query string, params OCRParams) ([]TextMatch, error)
    FindText runs OCR and returns word-level matches for the query string.

func (f *Finder) Has(pattern *Pattern) (bool, error)
    Has reports whether the target exists and bubbles non-find errors.

func (f *Finder) HasNext() bool
    HasNext reports whether the compatibility iterator has another match
    available.

func (f *Finder) Iterate(pattern *Pattern) error
    Iterate prepares a compatibility iterator over the best match. Unlike Find,
    a miss does not return ErrFindFailed. Call HasNext to inspect presence.

func (f *Finder) IterateAll(pattern *Pattern) error
    IterateAll prepares a compatibility iterator over all matches. Unlike Java
    SikuliX this additive Go surface keeps LastMatches available even after
    iteration.

func (f *Finder) LastMatches() []Match
    LastMatches returns a copy of the full most recent match set. It does not
    shrink as the compatibility iterator advances.

func (f *Finder) Next() (Match, bool)
    Next returns the next compatibility-iterator match and advances the
    iterator. It returns false when the iterator is empty or exhausted.

func (f *Finder) ReadText(params OCRParams) (string, error)
    ReadText runs OCR and returns normalized text.

func (f *Finder) Reset()
    Reset rewinds the compatibility iterator to the start of the most recent
    match set.

func (f *Finder) SetMatcher(m core.Matcher)
    SetMatcher overrides the matcher backend used by this finder.

func (f *Finder) SetOCRBackend(ocr core.OCR)
    SetOCRBackend overrides the OCR backend used by this finder.

func (f *Finder) Wait(pattern *Pattern, timeout time.Duration) (Match, error)

func (f *Finder) WaitAnyList(patterns []*Pattern, timeout time.Duration) ([]Match, error)

func (f *Finder) WaitBestList(patterns []*Pattern, timeout time.Duration) (Match, error)

func (f *Finder) WaitVanish(pattern *Pattern, timeout time.Duration) (bool, error)
    WaitVanish blocks until the pattern disappears or timeout expires.

type FinderAPI interface {
	Find(pattern *Pattern) (Match, error)
	FindAll(pattern *Pattern) ([]Match, error)
	FindAllByRow(pattern *Pattern) ([]Match, error)
	FindAllByColumn(pattern *Pattern) ([]Match, error)
	FindAnyList(patterns []*Pattern) ([]Match, error)
	FindBestList(patterns []*Pattern) (Match, error)
	Iterate(pattern *Pattern) error
	IterateAll(pattern *Pattern) error
	Exists(pattern *Pattern) (Match, bool, error)
	Has(pattern *Pattern) (bool, error)
	Wait(pattern *Pattern, timeout time.Duration) (Match, error)
	WaitAnyList(patterns []*Pattern, timeout time.Duration) ([]Match, error)
	WaitBestList(patterns []*Pattern, timeout time.Duration) (Match, error)
	WaitVanish(pattern *Pattern, timeout time.Duration) (bool, error)
	CollectWords(params OCRParams) ([]OCRWord, error)
	CollectLines(params OCRParams) ([]OCRLine, error)
	HasNext() bool
	Next() (Match, bool)
	Reset()
	Destroy()
	ReadText(params OCRParams) (string, error)
	FindText(query string, params OCRParams) ([]TextMatch, error)
	LastMatches() []Match
}
    FinderAPI performs match/OCR operations against a source image.
    Miss and timeout handling follows the canonical sikuli-go parity contract:
    Find returns ErrFindFailed on a miss, Exists returns (Match{}, false,
    nil), Wait returns ErrTimeout after the wait budget is exhausted, and
    WaitVanish returns false,nil on timeout. The additive compatibility iterator
    surface provides SikuliX-style traversal without removing the existing
    value/slice-oriented methods.

type Image struct {
	// Has unexported fields.
}

func NewImageFromAny(name string, src image.Image) (*Image, error)

func NewImageFromGray(name string, src *image.Gray) (*Image, error)

func NewImageFromMatrix(name string, rows [][]uint8) (*Image, error)

func (i *Image) Clone() *Image

func (i *Image) Crop(rect Rect) (*Image, error)

func (i *Image) Gray() *image.Gray

func (i *Image) Height() int

func (i *Image) Name() string

func (i *Image) Width() int

type ImageAPI interface {
	Name() string
	Width() int
	Height() int
	Gray() *image.Gray
	Clone() *Image
	Crop(rect Rect) (*Image, error)
}
    ImageAPI describes immutable image primitives used by matching and OCR. This
    aligns with the SikuliX notion of image snapshots used by Region/Finder.

type InputAPI interface {
	MoveMouse(x, y int, opts InputOptions) error
	Hover(x, y int, opts InputOptions) error
	Click(x, y int, opts InputOptions) error
	RightClick(x, y int, opts InputOptions) error
	DoubleClick(x, y int, opts InputOptions) error
	MouseDown(x, y int, opts InputOptions) error
	MouseUp(x, y int, opts InputOptions) error
	TypeText(text string, opts InputOptions) error
	Paste(text string, opts InputOptions) error
	Hotkey(keys ...string) error
	KeyDown(keys ...string) error
	KeyUp(keys ...string) error
	Wheel(x, y int, direction WheelDirection, steps int, opts InputOptions) error
	DragDrop(fromX, fromY, toX, toY int, opts InputOptions) error
}
    InputAPI exposes desktop input actions. This is the compatibility layer for
    click/type/hotkey style operations.

type InputController struct {
	// Has unexported fields.
}

func NewInputController() *InputController

func (c *InputController) Click(x, y int, opts InputOptions) error

func (c *InputController) DoubleClick(x, y int, opts InputOptions) error

func (c *InputController) DragDrop(fromX, fromY, toX, toY int, opts InputOptions) error

func (c *InputController) Hotkey(keys ...string) error

func (c *InputController) Hover(x, y int, opts InputOptions) error

func (c *InputController) KeyDown(keys ...string) error

func (c *InputController) KeyUp(keys ...string) error

func (c *InputController) MouseDown(x, y int, opts InputOptions) error

func (c *InputController) MouseUp(x, y int, opts InputOptions) error

func (c *InputController) MoveMouse(x, y int, opts InputOptions) error

func (c *InputController) Paste(text string, opts InputOptions) error

func (c *InputController) RightClick(x, y int, opts InputOptions) error

func (c *InputController) SetBackend(backend core.Input)

func (c *InputController) TypeText(text string, opts InputOptions) error

func (c *InputController) Wheel(x, y int, direction WheelDirection, steps int, opts InputOptions) error

type InputOptions struct {
	Delay  time.Duration
	Button MouseButton
}

type LiveRegion struct {
	// Has unexported fields.
}

func (r LiveRegion) Bounds() Region

func (r LiveRegion) Capture() (*Image, error)

func (r LiveRegion) Center() Point

func (r LiveRegion) Click(opts InputOptions) error

func (r LiveRegion) CollectLines(params OCRParams) ([]OCRLine, error)

func (r LiveRegion) CollectWords(params OCRParams) ([]OCRWord, error)

func (r LiveRegion) DoubleClick(opts InputOptions) error

func (r LiveRegion) DragDrop(target TargetPointProvider, opts InputOptions) error

func (r LiveRegion) Exists(pattern *Pattern, timeout time.Duration) (Match, bool, error)

func (r LiveRegion) Find(pattern *Pattern) (Match, error)

func (r LiveRegion) FindAnyList(patterns []*Pattern) ([]Match, error)

func (r LiveRegion) FindBestList(patterns []*Pattern) (Match, error)

func (r LiveRegion) FindText(query string, params OCRParams) ([]TextMatch, error)

func (r LiveRegion) Grow(dx, dy int) LiveRegion

func (r LiveRegion) Has(pattern *Pattern, timeout time.Duration) (bool, error)

func (r LiveRegion) Hover(opts InputOptions) error

func (r LiveRegion) KeyDown(keys ...string) error

func (r LiveRegion) KeyUp(keys ...string) error

func (r LiveRegion) MouseDown(opts InputOptions) error

func (r LiveRegion) MouseUp(opts InputOptions) error

func (r LiveRegion) MoveTo(x, y int) LiveRegion

func (r LiveRegion) Offset(dx, dy int) LiveRegion

func (r LiveRegion) Paste(text string, opts InputOptions) error

func (r LiveRegion) ReadText(params OCRParams) (string, error)

func (r LiveRegion) RightClick(opts InputOptions) error

func (r LiveRegion) SetSize(w, h int) LiveRegion

func (r LiveRegion) TargetPoint() Point

func (r LiveRegion) TypeText(text string, opts InputOptions) error

func (r LiveRegion) Wait(pattern *Pattern, timeout time.Duration) (Match, error)

func (r LiveRegion) WaitAnyList(patterns []*Pattern, timeout time.Duration) ([]Match, error)

func (r LiveRegion) WaitBestList(patterns []*Pattern, timeout time.Duration) (Match, error)

func (r LiveRegion) WaitVanish(pattern *Pattern, timeout time.Duration) (bool, error)

func (r LiveRegion) Wheel(direction WheelDirection, steps int, opts InputOptions) error

func (r LiveRegion) WithMatcherEngine(engine MatcherEngine) LiveRegion

type LiveRegionAPI interface {
	Bounds() Region
	Center() Point
	TargetPoint() Point
	Grow(dx, dy int) LiveRegion
	Offset(dx, dy int) LiveRegion
	MoveTo(x, y int) LiveRegion
	SetSize(w, h int) LiveRegion
	WithMatcherEngine(engine MatcherEngine) LiveRegion
	Capture() (*Image, error)
	Find(pattern *Pattern) (Match, error)
	FindAnyList(patterns []*Pattern) ([]Match, error)
	FindBestList(patterns []*Pattern) (Match, error)
	Exists(pattern *Pattern, timeout time.Duration) (Match, bool, error)
	Has(pattern *Pattern, timeout time.Duration) (bool, error)
	Wait(pattern *Pattern, timeout time.Duration) (Match, error)
	WaitAnyList(patterns []*Pattern, timeout time.Duration) ([]Match, error)
	WaitBestList(patterns []*Pattern, timeout time.Duration) (Match, error)
	WaitVanish(pattern *Pattern, timeout time.Duration) (bool, error)
	ReadText(params OCRParams) (string, error)
	FindText(query string, params OCRParams) ([]TextMatch, error)
	CollectWords(params OCRParams) ([]OCRWord, error)
	CollectLines(params OCRParams) ([]OCRLine, error)
	Hover(opts InputOptions) error
	Click(opts InputOptions) error
	RightClick(opts InputOptions) error
	DoubleClick(opts InputOptions) error
	MouseDown(opts InputOptions) error
	MouseUp(opts InputOptions) error
	TypeText(text string, opts InputOptions) error
	Paste(text string, opts InputOptions) error
	DragDrop(target TargetPointProvider, opts InputOptions) error
	Wheel(direction WheelDirection, steps int, opts InputOptions) error
	KeyDown(keys ...string) error
	KeyUp(keys ...string) error
}
    LiveRegionAPI defines screen-backed region operations that route through the
    API runtime.

type Location struct {
	X int
	Y int
}

func NewLocation(x, y int) Location

func (l Location) Move(dx, dy int) Location

func (l Location) String() string

func (l Location) TargetPoint() Point

func (l Location) ToPoint() Point

type Match struct {
	Rect
	Score  float64
	Target Point
	Index  int

	// Has unexported fields.
}

func NewMatch(x, y, w, h int, score float64, off Point) Match

func SearchExists(probe SearchProbe, timeout, interval time.Duration) (Match, bool, error)
    SearchExists applies the canonical sikuli-go parity contract to a search
    probe. Misses are reported as (Match{}, false, nil); timeout <= 0 performs
    one probe.

func SearchWait(probe SearchProbe, timeout, interval time.Duration) (Match, error)
    SearchWait applies the canonical sikuli-go wait contract to a search probe.
    Misses are promoted to ErrTimeout once the wait budget is exhausted.

func (m Match) Bounds() Region
    Bounds returns the match as a region-like value so callers can treat a live
    match the same way SikuliX documents region-capable match results.

func (m Match) Capture() (*Image, error)
    Capture captures the currently matched live region.

func (m Match) Center() Point
    Center returns the geometric center of the matched rectangle.

func (m Match) Click(opts InputOptions) error
    Click clicks the match target point.

func (m Match) CollectLines(params OCRParams) ([]OCRLine, error)
    CollectLines returns OCR line-level results inside the matched live region.

func (m Match) CollectWords(params OCRParams) ([]OCRWord, error)
    CollectWords returns OCR word-level results inside the matched live region.

func (m Match) DoubleClick(opts InputOptions) error
    DoubleClick performs two click actions against the match target point.

func (m Match) DragDrop(target TargetPointProvider, opts InputOptions) error
    DragDrop drags from the match target point to the target point.

func (m Match) Exists(pattern *Pattern, timeout time.Duration) (Match, bool, error)
    Exists probes within the matched live region.

func (m Match) Find(pattern *Pattern) (Match, error)
    Find searches again within the matched live region.

func (m Match) FindAnyList(patterns []*Pattern) ([]Match, error)

func (m Match) FindBestList(patterns []*Pattern) (Match, error)

func (m Match) FindText(query string, params OCRParams) ([]TextMatch, error)
    FindText searches OCR text inside the matched live region.

func (m Match) Has(pattern *Pattern, timeout time.Duration) (bool, error)
    Has reports whether the target exists within the matched live region.

func (m Match) Hover(opts InputOptions) error
    Hover is a parity-friendly alias for MoveMouse.

func (m Match) KeyDown(keys ...string) error
    KeyDown holds the provided keys.

func (m Match) KeyUp(keys ...string) error
    KeyUp releases the provided keys.

func (m Match) Live() bool
    Live reports whether this match is bound to a running sikuli-go runtime.

func (m Match) MouseDown(opts InputOptions) error
    MouseDown presses and holds the mouse button at the match target point.

func (m Match) MouseUp(opts InputOptions) error
    MouseUp releases the mouse button at the match target point.

func (m Match) MoveMouse(opts InputOptions) error
    MoveMouse moves the pointer to the match target point.

func (m Match) Paste(text string, opts InputOptions) error
    Paste focuses the match target point and pastes text into it.

func (m Match) ReadText(params OCRParams) (string, error)
    ReadText runs OCR inside the matched live region.

func (m Match) Region() Region
    Region is an alias for Bounds for parity-friendly call sites.

func (m Match) RightClick(opts InputOptions) error
    RightClick clicks the match target point with the right mouse button.

func (m Match) String() string

func (m Match) TargetPoint() Point
    TargetPoint returns the resolved click target point for this match.

func (m Match) TypeText(text string, opts InputOptions) error
    TypeText focuses the match target point and types text into it.

func (m Match) Wait(pattern *Pattern, timeout time.Duration) (Match, error)
    Wait waits for the target within the matched live region.

func (m Match) WaitAnyList(patterns []*Pattern, timeout time.Duration) ([]Match, error)

func (m Match) WaitBestList(patterns []*Pattern, timeout time.Duration) (Match, error)

func (m Match) WaitVanish(pattern *Pattern, timeout time.Duration) (bool, error)
    WaitVanish waits for the target to disappear from the matched live region.

func (m Match) Wheel(direction WheelDirection, steps int, opts InputOptions) error
    Wheel scrolls at the match target point.

type MatchAPI interface {
	Bounds() Region
	Region() Region
	Center() Point
	TargetPoint() Point
	Live() bool
	Capture() (*Image, error)
	Find(pattern *Pattern) (Match, error)
	FindAnyList(patterns []*Pattern) ([]Match, error)
	FindBestList(patterns []*Pattern) (Match, error)
	Exists(pattern *Pattern, timeout time.Duration) (Match, bool, error)
	Has(pattern *Pattern, timeout time.Duration) (bool, error)
	Wait(pattern *Pattern, timeout time.Duration) (Match, error)
	WaitAnyList(patterns []*Pattern, timeout time.Duration) ([]Match, error)
	WaitBestList(patterns []*Pattern, timeout time.Duration) (Match, error)
	WaitVanish(pattern *Pattern, timeout time.Duration) (bool, error)
	ReadText(params OCRParams) (string, error)
	FindText(query string, params OCRParams) ([]TextMatch, error)
	CollectWords(params OCRParams) ([]OCRWord, error)
	CollectLines(params OCRParams) ([]OCRLine, error)
	MoveMouse(opts InputOptions) error
	Hover(opts InputOptions) error
	Click(opts InputOptions) error
	RightClick(opts InputOptions) error
	DoubleClick(opts InputOptions) error
	MouseDown(opts InputOptions) error
	MouseUp(opts InputOptions) error
	TypeText(text string, opts InputOptions) error
	Paste(text string, opts InputOptions) error
	DragDrop(target TargetPointProvider, opts InputOptions) error
	Wheel(direction WheelDirection, steps int, opts InputOptions) error
	KeyDown(keys ...string) error
	KeyUp(keys ...string) error
}
    MatchAPI defines a live match result that can be used directly for follow-up
    search, capture, and current direct input verbs without manual point
    routing.

type MatcherEngine string
    MatcherEngine selects the server-side matcher implementation used for live
    screen queries.

const (
	MatcherEngineDefault  MatcherEngine = ""
	MatcherEngineTemplate MatcherEngine = "template"
	MatcherEngineORB      MatcherEngine = "orb"
	MatcherEngineHybrid   MatcherEngine = "hybrid"
	MatcherEngineAKAZE    MatcherEngine = "akaze"
	MatcherEngineBRISK    MatcherEngine = "brisk"
	MatcherEngineKAZE     MatcherEngine = "kaze"
	MatcherEngineSIFT     MatcherEngine = "sift"
)
type MouseButton string

const (
	MouseButtonLeft   MouseButton = "left"
	MouseButtonRight  MouseButton = "right"
	MouseButtonMiddle MouseButton = "middle"
)
type OCRLine struct {
	Rect
	Text       string
	Confidence float64
	Index      int
	Words      []OCRWord
}

type OCRParams struct {
	Language         string
	TrainingDataPath string
	MinConfidence    float64
	Timeout          time.Duration
	CaseSensitive    bool
}

type OCRWord struct {
	Rect
	Text       string
	Confidence float64
	Index      int
}

type ObserveAPI interface {
	ObserveAppear(source *Image, region Region, pattern *Pattern, opts ObserveOptions) ([]ObserveEvent, error)
	ObserveVanish(source *Image, region Region, pattern *Pattern, opts ObserveOptions) ([]ObserveEvent, error)
	ObserveChange(source *Image, region Region, opts ObserveOptions) ([]ObserveEvent, error)
}
    ObserveAPI exposes appear/vanish/change polling contracts for a region.

type ObserveEvent struct {
	Type      ObserveEventType
	Match     Match
	Timestamp time.Time
}

type ObserveEventType string

const (
	ObserveEventAppear ObserveEventType = "appear"
	ObserveEventVanish ObserveEventType = "vanish"
	ObserveEventChange ObserveEventType = "change"
)
type ObserveOptions struct {
	Interval time.Duration
	Timeout  time.Duration
}

type ObserverController struct {
	// Has unexported fields.
}

func NewObserverController() *ObserverController

func (c *ObserverController) ObserveAppear(source *Image, region Region, pattern *Pattern, opts ObserveOptions) ([]ObserveEvent, error)

func (c *ObserverController) ObserveChange(source *Image, region Region, opts ObserveOptions) ([]ObserveEvent, error)

func (c *ObserverController) ObserveVanish(source *Image, region Region, pattern *Pattern, opts ObserveOptions) ([]ObserveEvent, error)

func (c *ObserverController) SetBackend(backend core.Observer)

type Offset struct {
	X int
	Y int
}

func NewOffset(x, y int) Offset

func (o Offset) String() string

func (o Offset) ToPoint() Point

type Options struct {
	// Has unexported fields.
}

func NewOptions() *Options

func NewOptionsFromMap(entries map[string]string) *Options

func (o *Options) Clone() *Options

func (o *Options) Delete(key string)

func (o *Options) Entries() map[string]string

func (o *Options) GetBool(key string, def bool) bool

func (o *Options) GetFloat64(key string, def float64) float64

func (o *Options) GetInt(key string, def int) int

func (o *Options) GetString(key, def string) string

func (o *Options) Has(key string) bool

func (o *Options) Merge(other *Options)

func (o *Options) SetBool(key string, value bool)

func (o *Options) SetFloat64(key string, value float64)

func (o *Options) SetInt(key string, value int)

func (o *Options) SetString(key, value string)

type Pattern struct {
	// Has unexported fields.
}

func NewPattern(img *Image) (*Pattern, error)
    NewPattern creates a match pattern from an image with default similarity
    settings.

func (p *Pattern) Exact() *Pattern
    Exact is a convenience for Similar(1.0).

func (p *Pattern) Image() *Image
    Image returns the underlying pattern image.

func (p *Pattern) Mask() *image.Gray
    Mask returns the currently configured mask.

func (p *Pattern) Offset() Point
    Offset returns the configured click anchor offset.

func (p *Pattern) Resize(factor float64) *Pattern
    Resize scales the pattern before matching.

func (p *Pattern) ResizeFactor() float64
    ResizeFactor returns the currently configured resize factor.

func (p *Pattern) Similar(sim float64) *Pattern
    Similar sets the acceptance threshold in the [0,1] range. Higher values
    require a closer match.

func (p *Pattern) Similarity() float64
    Similarity returns the current acceptance threshold.

func (p *Pattern) TargetOffset(dx, dy int) *Pattern
    TargetOffset sets the click anchor relative to the matched rectangle.

func (p *Pattern) WithMask(mask *image.Gray) (*Pattern, error)
    WithMask sets an optional per-pixel mask where 0 excludes and >0 includes
    pixels.

func (p *Pattern) WithMaskMatrix(rows [][]uint8) (*Pattern, error)
    WithMaskMatrix sets an optional binary mask from matrix rows.

type PatternAPI interface {
	Image() *Image
	Similar(sim float64) *Pattern
	Similarity() float64
	Exact() *Pattern
	TargetOffset(dx, dy int) *Pattern
	Offset() Point
	Resize(factor float64) *Pattern
	ResizeFactor() float64
	Mask() *image.Gray
}
    PatternAPI configures how a target image should be matched on screen.
    It mirrors SikuliX Pattern behavior such as similar(), exact(), and
    targetOffset().

type Point struct {
	X int
	Y int
}

func NewPoint(x, y int) Point

func (p Point) TargetPoint() Point

func (p Point) ToLocation() Location
    ToLocation converts a point to a parity-friendly Location value.

func (p Point) ToOffset() Offset
    ToOffset converts a point to a parity-friendly Offset value.

type Rect struct {
	X int
	Y int
	W int
	H int
}

func NewRect(x, y, w, h int) Rect

func (r Rect) Contains(p Point) bool

func (r Rect) Empty() bool

func (r Rect) String() string

type Region struct {
	Rect
	// ThrowException is retained as parity metadata for SikuliX-style ports.
	// The Go API uses explicit return values for misses and timeouts regardless of this flag.
	ThrowException  bool
	AutoWaitTimeout float64
	WaitScanRate    float64
	ObserveScanRate float64
}

func NewRegion(x, y, w, h int) Region
    NewRegion constructs a rectangular search area with default timing settings.

func (r Region) Center() Point
    Center returns the midpoint of the region.

func (r Region) CollectLines(source *Image, params OCRParams) ([]OCRLine, error)
    CollectLines runs OCR in region and returns line-level results.

func (r Region) CollectWords(source *Image, params OCRParams) ([]OCRWord, error)
    CollectWords runs OCR in region and returns word-level results.

func (r Region) Contains(p Point) bool
    Contains reports whether a point lies within the region.

func (r Region) ContainsLocation(loc Location) bool
    ContainsLocation reports whether this region contains the given location.

func (r Region) ContainsRegion(other Region) bool

func (r Region) Count(source *Image, pattern *Pattern) (int, error)
    Count returns the number of matches found in this region.

func (r Region) Exists(source *Image, pattern *Pattern, timeout time.Duration) (Match, bool, error)
    Exists checks for pattern presence within timeout and returns first match
    when found.

func (r Region) Find(source *Image, pattern *Pattern) (Match, error)

func (r Region) FindAll(source *Image, pattern *Pattern) ([]Match, error)
    FindAll returns all matches in this region.

func (r Region) FindAllByColumn(source *Image, pattern *Pattern) ([]Match, error)

func (r Region) FindAllByRow(source *Image, pattern *Pattern) ([]Match, error)

func (r Region) FindAnyList(source *Image, patterns []*Pattern) ([]Match, error)

func (r Region) FindBestList(source *Image, patterns []*Pattern) (Match, error)

func (r Region) FindText(source *Image, query string, params OCRParams) ([]TextMatch, error)
    FindText runs OCR in region and returns matches for the query.

func (r Region) Grow(dx, dy int) Region
    Grow expands the region outward in both directions.

func (r Region) Has(source *Image, pattern *Pattern, timeout time.Duration) (bool, error)

func (r Region) Intersection(other Region) Region
    Intersection returns the overlap between this region and another.

func (r Region) MoveTo(x, y int) Region

func (r Region) MoveToLocation(loc Location) Region
    MoveToLocation moves this region using a Location alias.

func (r Region) Offset(dx, dy int) Region
    Offset translates the region by dx and dy.

func (r Region) OffsetBy(off Offset) Region
    OffsetBy applies an Offset alias to this region position.

func (r Region) ReadText(source *Image, params OCRParams) (string, error)

func (r *Region) ResetThrowException()

func (r *Region) SetAutoWaitTimeout(sec float64)

func (r *Region) SetObserveScanRate(rate float64)

func (r Region) SetSize(w, h int) Region
    SetSize updates width and height while clamping negatives to zero.

func (r *Region) SetThrowException(flag bool)

func (r *Region) SetWaitScanRate(rate float64)

func (r Region) TargetPoint() Point

func (r Region) Union(other Region) Region
    Union returns the smallest region containing both regions.

func (r Region) Wait(source *Image, pattern *Pattern, timeout time.Duration) (Match, error)

func (r Region) WaitAnyList(source *Image, patterns []*Pattern, timeout time.Duration) ([]Match, error)

func (r Region) WaitBestList(source *Image, patterns []*Pattern, timeout time.Duration) (Match, error)

func (r Region) WaitVanish(source *Image, pattern *Pattern, timeout time.Duration) (bool, error)
    WaitVanish waits until pattern disappears or timeout expires.

type RegionAPI interface {
	Center() Point
	Grow(dx, dy int) Region
	Offset(dx, dy int) Region
	MoveTo(x, y int) Region
	SetSize(w, h int) Region
	Contains(p Point) bool
	ContainsRegion(other Region) bool
	Union(other Region) Region
	Intersection(other Region) Region
	Find(source *Image, pattern *Pattern) (Match, error)
	Exists(source *Image, pattern *Pattern, timeout time.Duration) (Match, bool, error)
	Has(source *Image, pattern *Pattern, timeout time.Duration) (bool, error)
	Wait(source *Image, pattern *Pattern, timeout time.Duration) (Match, error)
	WaitVanish(source *Image, pattern *Pattern, timeout time.Duration) (bool, error)
	FindAll(source *Image, pattern *Pattern) ([]Match, error)
	FindAllByRow(source *Image, pattern *Pattern) ([]Match, error)
	FindAllByColumn(source *Image, pattern *Pattern) ([]Match, error)
	FindAnyList(source *Image, patterns []*Pattern) ([]Match, error)
	FindBestList(source *Image, patterns []*Pattern) (Match, error)
	WaitAnyList(source *Image, patterns []*Pattern, timeout time.Duration) ([]Match, error)
	WaitBestList(source *Image, patterns []*Pattern, timeout time.Duration) (Match, error)
	ReadText(source *Image, params OCRParams) (string, error)
	FindText(source *Image, query string, params OCRParams) ([]TextMatch, error)
	CollectWords(source *Image, params OCRParams) ([]OCRWord, error)
	CollectLines(source *Image, params OCRParams) ([]OCRLine, error)
}
    RegionAPI defines region geometry and region-scoped automation operations.
    It maps to familiar SikuliX Region methods while keeping the same explicit
    Go miss/timeout contract used by FinderAPI.

type Runtime struct {
	// Has unexported fields.
}

func NewRuntime(address string, opts ...RuntimeOption) (*Runtime, error)
    NewRuntime connects to a running sikuli-go API runtime and exposes live
    screen operations.

func (r *Runtime) Address() string

func (r *Runtime) Capture() (*Image, error)

func (r *Runtime) CaptureRegion(region Region) (*Image, error)

func (r *Runtime) Close() error

func (r *Runtime) PrimaryScreen() (Screen, error)

func (r *Runtime) Region(region Region) LiveRegion

func (r *Runtime) Screen(id int) (Screen, error)

func (r *Runtime) Screens() ([]Screen, error)

type RuntimeAPI interface {
	Address() string
	Close() error
	Screens() ([]Screen, error)
	PrimaryScreen() (Screen, error)
	Screen(id int) (Screen, error)
	Capture() (*Image, error)
	CaptureRegion(region Region) (*Image, error)
	Region(region Region) LiveRegion
}
    RuntimeAPI defines the public live runtime client used to discover screens
    and capture/search them.

type RuntimeOption func(*runtimeConfig)

func WithRuntimeAuthToken(token string) RuntimeOption

func WithRuntimeConn(conn *grpc.ClientConn) RuntimeOption

func WithRuntimeContextDialer(dialer func(context.Context, string) (net.Conn, error)) RuntimeOption

func WithRuntimeDialTimeout(timeout time.Duration) RuntimeOption

func WithRuntimeMatcherEngine(engine MatcherEngine) RuntimeOption

func WithRuntimeRPCTimeout(timeout time.Duration) RuntimeOption

type RuntimeSettings struct {
	ImageCache      int
	ShowActions     bool
	WaitScanRate    float64
	ObserveScanRate float64
	AutoWaitTimeout float64
	MinSimilarity   float64
	// FindFailedThrows is retained as parity metadata for SikuliX-style ports.
	// The Go API uses explicit return values for misses and timeouts regardless of this flag.
	FindFailedThrows bool
}

func GetSettings() RuntimeSettings

func ResetSettings() RuntimeSettings

func UpdateSettings(apply func(*RuntimeSettings)) RuntimeSettings

type Screen struct {
	ID      int
	Name    string
	Bounds  Rect
	Primary bool
	// Has unexported fields.
}

func NewScreen(id int, bounds Rect) Screen
    NewScreen constructs a logical screen descriptor.

func (s Screen) Capture() (*Image, error)

func (s Screen) Click(opts InputOptions) error

func (s Screen) CollectLines(params OCRParams) ([]OCRLine, error)

func (s Screen) CollectWords(params OCRParams) ([]OCRWord, error)

func (s Screen) DoubleClick(opts InputOptions) error

func (s Screen) DragDrop(target TargetPointProvider, opts InputOptions) error

func (s Screen) Exists(pattern *Pattern, timeout time.Duration) (Match, bool, error)

func (s Screen) Find(pattern *Pattern) (Match, error)

func (s Screen) FindAnyList(patterns []*Pattern) ([]Match, error)

func (s Screen) FindBestList(patterns []*Pattern) (Match, error)

func (s Screen) FindText(query string, params OCRParams) ([]TextMatch, error)

func (s Screen) FullRegion() LiveRegion

func (s Screen) Has(pattern *Pattern, timeout time.Duration) (bool, error)

func (s Screen) Hover(opts InputOptions) error

func (s Screen) KeyDown(keys ...string) error

func (s Screen) KeyUp(keys ...string) error

func (s Screen) Live() bool

func (s Screen) MouseDown(opts InputOptions) error

func (s Screen) MouseUp(opts InputOptions) error

func (s Screen) Paste(text string, opts InputOptions) error

func (s Screen) ReadText(params OCRParams) (string, error)

func (s Screen) Region(x, y, w, h int) LiveRegion

func (s Screen) RegionRect(rect Rect) LiveRegion

func (s Screen) RightClick(opts InputOptions) error

func (s Screen) TargetPoint() Point

func (s Screen) TypeText(text string, opts InputOptions) error

func (s Screen) Wait(pattern *Pattern, timeout time.Duration) (Match, error)

func (s Screen) WaitAnyList(patterns []*Pattern, timeout time.Duration) ([]Match, error)

func (s Screen) WaitBestList(patterns []*Pattern, timeout time.Duration) (Match, error)

func (s Screen) WaitVanish(pattern *Pattern, timeout time.Duration) (bool, error)

func (s Screen) Wheel(direction WheelDirection, steps int, opts InputOptions) error

type ScreenAPI interface {
	Live() bool
	TargetPoint() Point
	FullRegion() LiveRegion
	Region(x, y, w, h int) LiveRegion
	RegionRect(rect Rect) LiveRegion
	Capture() (*Image, error)
	Find(pattern *Pattern) (Match, error)
	FindAnyList(patterns []*Pattern) ([]Match, error)
	FindBestList(patterns []*Pattern) (Match, error)
	Exists(pattern *Pattern, timeout time.Duration) (Match, bool, error)
	Has(pattern *Pattern, timeout time.Duration) (bool, error)
	Wait(pattern *Pattern, timeout time.Duration) (Match, error)
	WaitAnyList(patterns []*Pattern, timeout time.Duration) ([]Match, error)
	WaitBestList(patterns []*Pattern, timeout time.Duration) (Match, error)
	WaitVanish(pattern *Pattern, timeout time.Duration) (bool, error)
	ReadText(params OCRParams) (string, error)
	FindText(query string, params OCRParams) ([]TextMatch, error)
	CollectWords(params OCRParams) ([]OCRWord, error)
	CollectLines(params OCRParams) ([]OCRLine, error)
	Hover(opts InputOptions) error
	Click(opts InputOptions) error
	RightClick(opts InputOptions) error
	DoubleClick(opts InputOptions) error
	MouseDown(opts InputOptions) error
	MouseUp(opts InputOptions) error
	TypeText(text string, opts InputOptions) error
	Paste(text string, opts InputOptions) error
	DragDrop(target TargetPointProvider, opts InputOptions) error
	Wheel(direction WheelDirection, steps int, opts InputOptions) error
	KeyDown(keys ...string) error
	KeyUp(keys ...string) error
}
    ScreenAPI defines live screen selection, capture, and search operations.

type SearchProbe func() (Match, error)
    SearchProbe returns the next match candidate for a parity search operation.
    Returning ErrFindFailed indicates a miss; any other error aborts the search.

type TargetPointProvider interface {
	TargetPoint() Point
}
    TargetPointProvider describes values that can resolve to a concrete action
    target.

type TextMatch struct {
	Rect
	Text       string
	Confidence float64
	Index      int
}

type WheelDirection string

const (
	WheelDirectionUp    WheelDirection = "up"
	WheelDirectionDown  WheelDirection = "down"
	WheelDirectionLeft  WheelDirection = "left"
	WheelDirectionRight WheelDirection = "right"
)
type Window struct {
	ID      string
	App     string
	PID     int
	Title   string
	Bounds  Rect
	Focused bool
}

type WindowQuery struct {
	ID            string
	TitleExact    string
	TitleContains string
	FocusedOnly   bool
	Index         int
}