Macro Handler

Macro Handler

Android Automation Platform

Object MethodScanning and Detection

Capture.compareImages(left, right, method, threshold?, pixelTolerance?, backgroundTolerance?, timeoutMs?)

Compares two Base64 crops locally and returns a status, similarity score and match table. Supports RGB, grayscale, edges, single-object appearance, object shape and three color measurements. Object methods require one complete object surrounded by a uniform or transparent border.

Documented for app version 1.0.59Updated:

Detailed Explanation

This section explains when to use the API, how to call it, and which structures it works best with in production flow.

How To Call It

Capture is a global table: call its functions with a dot (Capture.<method>(...)), not a colon.

When To Use It

In detection flow, refresh the screen with Snap.screenRefresh() first, then narrow the search area and confidence using Region and FindParam.

Parameters and Return

left/right are Base64 images. method: image_rgb, image_gray, image_edges, image_object, image_object_shape, color_average, color_histogram or color_layout. Optional threshold 0.5–1 (0.9), pixelTolerance 0–64 (16), backgroundTolerance 0–64 (24), timeoutMs 1–60000 (2000). RGB/grayscale/object appearance use pixel tolerance; edges use a minimum edge strength of 8; object methods use background tolerance. Color measurements and object shape do not use pixel tolerance. Returns matched, status, score (0–1), reason. Status: matched, not_found, unreadable, invalid_reference, invalid_target, timeout. Invalid options or images raise errors; stop requests propagate. Each image is limited to 950000 Base64 characters and 4194304 pixels; measurements sample up to 256 pixels per side. Scores are not probabilities. Does not locate objects within a larger region or return coordinates; multi-object, clipped or ambiguous-background object crops are rejected. Average color and color distribution ignore position; color_layout uses a 4×4 grid. Images are not sent to a server.

Best Combined With

It is typically combined with Snap, Region, Asset, and FindParam; you can feed the result into quickTap(), click(), or a follow-up OCR step.

Example Usage

The snippet below is a starter pattern that can be applied directly in runtime flow.

lua
Try in Editor →
local a = Capture.regionToBase64(Region(20, 100, 120, 120), "png", 100)
local b = Capture.regionToBase64(Region(220, 100, 120, 120), "png", 100)
local result = Capture.compareImages(a, b, "image_object", 0.9, 16, 24, 2000)
if result.matched then
  print("Similarity: " .. result.score)
else
  print(result.status .. ": " .. result.reason)
end

Copyable Progressive Examples

From foundation to combined usage, each level is provided as a separate code block so you can copy the level you need and adapt it directly.

Foundation

Shows the shortest direct way to call the API.

Foundation
lua
Try in Editor →
local a = Capture.regionToBase64(Region(20, 100, 120, 120), "png", 100)
local b = Capture.regionToBase64(Region(220, 100, 120, 120), "png", 100)
local result = Capture.compareImages(a, b, "image_object", 0.9, 16, 24, 2000)
if result.matched then
  print("Similarity: " .. result.score)
else
  print(result.status .. ": " .. result.reason)
end

Simple

Wraps the base call with minimal flow control.

Simple
lua
Try in Editor →
local stepOk = true
local a = Capture.regionToBase64(Region(20, 100, 120, 120), "png", 100)
local b = Capture.regionToBase64(Region(220, 100, 120, 120), "png", 100)
local result = Capture.compareImages(a, b, "image_object", 0.9, 16, 24, 2000)
if result.matched then
  print("Similarity: " .. result.score)
else
  print(result.status .. ": " .. result.reason)
end
if stepOk then
  wait(200)
end

Practical Flow

A practical pattern for real macros with pcall, logging, and guards.

Practical Flow
lua
Try in Editor →
local ok, err = pcall(function()
  local a = Capture.regionToBase64(Region(20, 100, 120, 120), "png", 100)
  local b = Capture.regionToBase64(Region(220, 100, 120, 120), "png", 100)
  local result = Capture.compareImages(a, b, "image_object", 0.9, 16, 24, 2000)
  if result.matched then
    print("Similarity: " .. result.score)
  else
    print(result.status .. ": " .. result.reason)
  end
end)

if not ok then
  print("API step failed: Capture.compareImages: " .. tostring(err))
  requestStop()
end

Detailed

This level packages the API into a reusable helper with error reporting.

Detailed
lua
Try in Editor →
-- In detection flow, refresh the screen with Snap.screenRefresh() first, then narrow the search area and confidence using Region and FindParam.
local function run_compareimages_step()
  local a = Capture.regionToBase64(Region(20, 100, 120, 120), "png", 100)
  local b = Capture.regionToBase64(Region(220, 100, 120, 120), "png", 100)
  local result = Capture.compareImages(a, b, "image_object", 0.9, 16, 24, 2000)
  if result.matched then
    print("Similarity: " .. result.score)
  else
    print(result.status .. ": " .. result.reason)
  end
end

local ok, err = pcall(run_compareimages_step)
if not ok then
  toast("Step failed")
  print(err)
end

Combined

Combines the API with related structures to form a more realistic workflow.

Combined
lua
Try in Editor →
Snap.screenRefresh()
local a = Capture.regionToBase64(Region(20, 100, 120, 120), "png", 100)
local b = Capture.regionToBase64(Region(220, 100, 120, 120), "png", 100)
local result = Capture.compareImages(a, b, "image_object", 0.9, 16, 24, 2000)
if result.matched then
  print("Similarity: " .. result.score)
else
  print(result.status .. ": " .. result.reason)
end

local target = Region():find(Asset.image("target"), FindParam.timeout(3000))
if target then
  quickTap(target)
end
toast("Detection step completed")