Skip to content

screen ​

In CatScript, colors are represented in hexadecimal format (int type). For example:

NameHexCatScript Representation
Red#FF00000xFF0000
Green#00FF000x00FF00
Blue#0000FF0x0000FF

Color precision

precision=1.0 requires exact RGB equality. Lower values accept more color difference, and higher values are stricter.

screen.size() ​

Get the screen size.

python
screen.size() -> tuple[int, int]

Arguments ​

None.

Return ​

TypeDescription
tuple[int, int]The screen size in pixels.

Example ​

python
from catscript import screen, sys

if __name__ == "__main__":
    (w, h) = screen.size()
    sys.log(f"Screen size: ({w}, {h}).")

screen.snapshot() ​

Save a screenshot to a file.

python
screen.snapshot(path: str, region: tuple[int, int, int, int] = (0, 0, -1, -1), scale: float = 1.0) -> None

Arguments ​

NameTypeDefaultDescription
pathstrPath to save the screenshot.
regiontuple[int, int, int, int](0, 0, -1, -1)The capture region as (x1, y1, x2, y2). Use -1 for x2 or y2 to mean the screen edge.
scalefloat1.0Screenshot scaling ratio, ranging from 0.1 to 1.0.

Return ​

None.

Example ​

python
from catscript import screen

if __name__ == "__main__":
    screen.snapshot("/tmp/snapshot.png", region=(0, 0, 500, 500), scale=0.5)

screen.color() ​

Get the color at a screen coordinate.

python
screen.color(x: int, y: int) -> int

Arguments ​

NameTypeDefaultDescription
xintCoordinate x.
yintCoordinate y.

Return ​

TypeDescription
intThe color.

Example ​

python
from catscript import screen, sys

if __name__ == "__main__":
    color = screen.color(100, 100)
    sys.log(f"The color is {color:#06x}.")

screen.is_color() ​

Check whether the pixels at the given coordinates match the expected colors.

TIP

You can quickly generate the code for this function using the code template feature in CatScript's developer tools.

python
screen.is_color(colors: list[tuple[int, int, int]], precision: float = 1.0) -> bool

Arguments ​

NameTypeDefaultDescription
colorslist[tuple[int, int, int]]The list of coordinate colors to compare.
precisionfloat1.0Match strictness. 1.0 requires exact RGB equality; lower values are more tolerant.

Return ​

TypeDescription
boolWhether it meets the condition.

Example ​

python
from catscript import screen, sys

if __name__ == "__main__":
    if screen.is_color(
        [
            (378, 474, 0x4D92B1),
            (191, 357, 0x96988B),
            (397, 232, 0x21808A),
        ],
        precision=0.9,
    ):
        sys.log("Yes.")
    else:
        sys.log("No.")

screen.find_color() ​

Find pixels that match a color.

TIP

You can quickly generate the code for this function using the code template feature in CatScript's developer tools.

python
screen.find_color(color: int, offset: list[tuple[int, int, int]] = [], precision: float = 1.0, region: tuple[int, int, int, int] = (0, 0, -1, -1), max_miss: int = 0, all: bool = False) -> list[tuple[int, int]]

Arguments ​

NameTypeDefaultDescription
colorintThe color to find.
offsetlist[tuple[int, int, int]][]Additional color checks relative to each candidate.
precisionfloat1.0Match strictness. 1.0 requires exact RGB equality; lower values are more tolerant.
regiontuple[int, int, int, int](0, 0, -1, -1)The region as (x1, y1, x2, y2). Use -1 for x2 or y2 to mean the screen edge.
max_missint0The number of offset checks that may fail.
allboolFalseWhether to return all matching coordinates.

Return ​

TypeDescription
list[tuple[int, int]]Matching coordinates. (-1, -1) means no match was found.

Example ​

python
from catscript import screen, sys

if __name__ == "__main__":
    # Find the red color on the screen.
    (x, y) = screen.find_color(0xFF0000)[0]
    if x != -1 and y != -1:
        sys.log(f"Color is at ({x}, {y}).")
    else:
        sys.log("Not found.")
python
from catscript import screen, sys

if __name__ == "__main__":
    # Find red color on the screen, assuming its coordinates are (x, y), with the requirement:
    # - the color at the position (x + 10, y - 10) is green
    # - the color at the position (x + 20, y + 30) is blue.
    (x, y) = screen.find_color(
        0xFF0000, offset=[(10, -10, 0x00FF00), (20, 30, 0x0000FF)]
    )[0]
    if x != -1 and y != -1:
        sys.log(f"Color is at ({x}, {y}).")
    else:
        sys.log("Not found.")
python
from catscript import screen, sys

if __name__ == "__main__":
    # Find red color on the screen region (0, 0, 500, 500), assuming its coordinates are (x, y), with the requirement:
    # - the color at the position (x + 10, y - 10) is green.
    # - the color at the position (x + 20, y + 30) is blue.
    #
    # Additionally:
    # - Precision is 0.9 when comparing colors.
    # - Allow one offset check to fail.
    # - Return all matching coordinates.
    coordinates = screen.find_color(
        0xFF0000,
        offset=[(10, -10, 0x00FF00), (20, 30, 0x0000FF)],
        precision=0.9,
        region=(0, 0, 500, 500),
        max_miss=1,
        all=True,
    )
    if coordinates[0][0] != -1 and coordinates[0][1] != -1:
        for index, (x, y) in enumerate(coordinates):
            sys.log(f"<{index}>: ({x}, {y}).")
    else:
        sys.log("Not found.")

screen.find_image() ​

Find an image on the screen.

python
screen.find_image(path: str, ignore: list[int] = [], precision: float = 1.0, region: tuple[int, int, int, int] = (0, 0, -1, -1), max_miss: int = 0, all: bool = False) -> list[tuple[int, int]]

Arguments ​

NameTypeDefaultDescription
pathstrPath to the image to find.
ignorelist[int][]Colors to ignore during comparison, treated as transparent.
precisionfloat1.0Match strictness. 1.0 requires exact RGB equality; lower values are more tolerant.
regiontuple[int, int, int, int](0, 0, -1, -1)The region as (x1, y1, x2, y2). Use -1 for x2 or y2 to mean the screen edge.
max_missint0The number of pixel checks that may fail.
allboolFalseWhether to return all matching coordinates.

Return ​

TypeDescription
list[tuple[int, int]]Matching coordinates. (-1, -1) means no match was found.

Example ​

python
from catscript import screen, sys

if __name__ == "__main__":
    # Find the image of the path /tmp/a.png on the screen region (0, 0, 500, 500).
    #
    # Additionally:
    # - Ignore white and black pixels (treated as transparent).
    # - Precision is 0.9 when comparing colors.
    # - Allow one pixel check to fail.
    # - Return all matching coordinates.
    (x, y) = screen.find_image(
        "/tmp/a.png",
        ignore=[0xFFFFFF, 0x000000],
        precision=0.9,
        region=(0, 0, 500, 500),
        max_miss=1,
        all=False,
    )[0]
    if x != -1 and y != -1:
        sys.log(f"Image is at ({x}, {y}).")
    else:
        sys.log("Not found.")

Python automation for jailbroken iOS