CogniTabScript documentation
/

Template

Class

Use a saved image as a recognition target. You can resize or crop it into a separate Template, then save the result with save_as().

Syntax

Template(name, /)

Constructor parameters

NameDescription
nameString
Saved template in the current macro, for example "buttons/top/attack". An empty, missing, or ambiguous name raises an error; this does not capture a new image.
Required · Positional only
No default

Returns

Template

Example

base = Template("enemy_head")
variant = base.scale(0.9).crop(Region(0, 0, 64, 64)).save_as("enemy_head_small")

Fields

NameDescription
nameString?
Template name or relative folder path in the current macro; None for an unnamed image.
Constructor example
base = Template("enemy_head")

Methods

6 methods

Template.exists

Static Method

Check whether a template name exists in the current macro.

Syntax

Template.exists(name)

Parameters

NameDescription
nameString
Template name or relative folder path to check.
Required · Positional or named
No default

Returns

Boolean — true if the template exists.

Example

if Template.exists("enemy_head"):
    text("ready")

Template.similarity

Method

Compare the overall light and dark pattern of two images. Unreadable images or different image dimensions raise an error. The comparison ignores transparency and may miss color, brightness, or small detail changes; 100 does not mean identical pixels.

Syntax

template.similarity(other)

Parameters

NameDescription
otherTemplate
Required template with the same image width and height.
Required · Positional or named
No default

Returns

Number — Similarity from 0 to 100, in steps of 1.5625; higher means a more similar light and dark pattern.

Example

# Compare two saved templates of the same size.
before = Template("before")
after = Template("after")
score = before.similarity(after)
print(score)

Template.exists

Method

Check whether this Template's image file still exists. This does not check whether the image is readable.

Syntax

template.exists()

Returns

Boolean — true if the backing template file exists.

Example

t = Template("enemy_head")
if t.exists():
    text("ok")

Template.scale

Method

Resize the image and return a separate Template without changing the source. Use save_as() to keep it under a chosen name.

Syntax

template.scale(scale, scale_y=None)

Parameters

NameDescription
scaleNumber
Width multiplier: 1 keeps the width, 0.5 halves it, 2 doubles it. Values below 0.01 use 0.01. Also applies to height when scale_y is omitted.
Required · Positional or named
No default
scale_yNumber
Height multiplier, with a minimum of 0.01. Omit it to keep the original proportions.
Optional · Positional or named
Default: scale

Returns

Template — Scaled template object.

Example

t = Template("enemy_head")
small = t.scale(0.8)
hit = Region(0, 0, 1080, 2400).find(small, 3000)

Template.crop

Method

Cut out part of the image and return a separate Template without changing the source. Use save_as() to keep it under a chosen name.

Syntax

template.crop(region)

Parameters

NameDescription
regionRegion
Crop rectangle in image pixels, measured from the image's top-left corner, not the screen. Coordinates are truncated to integers and clipped to the image edges.
Required · Positional or named
No default

Returns

Template — Cropped template object.

Example

t = Template("enemy_head")
face = t.crop(Region(10, 10, 60, 60))

Template.save_as

Method

Save the image in the current macro and return the saved Template. Protected macros cannot save templates; a missing source file raises an error.

Syntax

template.save_as(name)

Parameters

NameDescription
nameString
Non-empty name or relative folder path, for example "buttons/top/attack". An existing image at that path is replaced.
Required · Positional or named
No default

Returns

Template — Saved named template object.

Example

captured = Region(200, 300, 120, 90).capture()
saved = captured.save_as("buttons/top/enemy_slot")
if saved.exists():
    text("saved")