Locators
askui.locators.AiElement
Locator for finding ui elements by data (e.g., image) collected with the AskUIRemoteDeviceSnippingTool using the name
assigned to the AI element during snipping to retrieve the data used for locating the ui element(s).
Arguments:
name
str - Name of the AI elementthreshold
float, optional - A threshold for how similar UI elements need to be to the image to be considered a match. Takes values between0.0
(= all elements are recognized) and1.0
(= elements need to look exactly like defined). Defaults to0.5
. Important: The threshold impacts the prediction quality.stop_threshold
float | None, optional - A threshold for when to stop searching for UI elements similar to the image. As soon as UI elements have been found that are at least as similar as thestop_threshold
, the search stops. Should be greater than or equal tothreshold
. Takes values between0.0
and1.0
. Defaults to value ofthreshold
if not provided. Important: Thestop_threshold
impacts the prediction speed.mask
list[tuple[float, float]] | None, optional - A polygon to match only a certain area of the image. Must have at least 3 points. Defaults toNone
.rotation_degree_per_step
int, optional - A step size in rotation degree. Rotates the image by rotation_degree_per_step until 360° is exceeded. Range is between0°
-360°
. Defaults to0°
. Important: This increases the prediction time quite a bit. So only use it when absolutely necessary.name
str | None, optional - Name for the image. Defaults to random name.image_compare_format
Literal[“RGB”, “grayscale”, “edges”], optional - A color compare style. Defaults to'grayscale'
. Important: Theimage_compare_format
impacts the prediction time as well as quality. As a rule of thumb,'edges'
is likely to be faster than'grayscale'
and'grayscale'
is likely to be faster than'RGB'
. For quality it is most often the other way around.
askui.locators.CircularDependencyError
Exception raised for circular dependencies in locator relations.
askui.locators.Element
Locator for finding ui elements by their class.
Arguments:
class_name
Literal[“text”, “textfield”] | None, optional - The class of the ui element, e.g.,'text'
or'textfield'
. Defaults toNone
.
Examples:
askui.locators.Image
Locator for finding ui elements by an image.
Arguments:
image
Union[PIL.Image.Image, pathlib.Path, str] - The image to match against (PIL Image, path, or string)threshold
float, optional - A threshold for how similar UI elements need to be to the image to be considered a match. Takes values between0.0
(= all elements are recognized) and1.0
(= elements need to look exactly like defined). Defaults to0.5
. Important: The threshold impacts the prediction quality.stop_threshold
float | None, optional - A threshold for when to stop searching for UI elements similar to the image. As soon as UI elements have been found that are at least as similar as thestop_threshold
, the search stops. Should be greater than or equal tothreshold
. Takes values between0.0
and1.0
. Defaults to value ofthreshold
if not provided. Important: Thestop_threshold
impacts the prediction speed.mask
list[tuple[float, float]] | None, optional - A polygon to match only a certain area of the image. Must have at least 3 points. Defaults toNone
.rotation_degree_per_step
int, optional - A step size in rotation degree. Rotates the image byrotation_degree_per_step
until 360° is exceeded. Range is between0°
-360°
. Defaults to0°
. Important: This increases the prediction time quite a bit. So only use it when absolutely necessary.name
str | None, optional - Name for the image. Defaults to random name.image_compare_format
Literal[“RGB”, “grayscale”, “edges”], optional - A color compare style. Defaults to'grayscale'
. Important: Theimage_compare_format
impacts the prediction time as well as quality. As a rule of thumb,'edges'
is likely to be faster than'grayscale'
and'grayscale'
is likely to be faster than'RGB'
. For quality it is most often the other way around.
Examples:
askui.locators.Locator
Abstract base class for all locators. Cannot be instantiated directly. Subclassed by all locators, e.g., Prompt
, Text
, Image
, etc.
askui.locators.Prompt
Locator for finding ui elements by a textual prompt / description of a ui element, e.g., “green sign up button”.
Arguments:
prompt
str - A textual prompt / description of a ui element, e.g.,"green sign up button"
Examples:
askui.locators.ReferencePoint
Defines under which conditions an element A is considered to be above, below, right or left of another element B.
"center"
: A is considered to be above, below, right or left of B if it is above, below, right or left of A’s center (in a straight vertical or horizontal line).
Examples:
A being above B (imaginary straight vertical line also shown):
A NOT being above B (imaginary straight vertical line also shown):
"boundary"
: A is considered to be above, below, right or left of B if it is above, below, right or left of (any point of the bounding box of) A (in a straight vertical or horizontal line).
Examples:
A being above B (imaginary straight vertical line also shown):
A NOT being above B (imaginary straight vertical line also shown):
"any"
: A is considered to be above, below, right or left of B if it is above, below, right or left of B no matter if it can be reached in a straight vertical or horizontal line from (a point of the bounding box of) A.
Examples:
A being above B:
A NOT being above B:
askui.locators.Relatable
Abstract base class for locators that can be related to other locators, e.g., spatially, logically etc. Cannot be instantiated directly. Subclassed by all (relatable) locators, e.g., Prompt
, Text
, Image
, etc.
above_of
Defines the element (located by self) to be above another element / other elements (located by other_locator).
An element A is considered to be above another element / other elements B
- if most of A (or, more specifically, A’s bounding box) is above B (or, more specifically, the top border of B’s bounding box) and
- if the bottom border of A (or, more specifically, A’s bounding box) is above the bottom border of B (or, more specifically, B’s bounding box).
Arguments:
other_locator
Relatable - Locator for an element / elements to relate toindex
RelationIndex, optional - Index of the element (located by self) above the other element(s) (located by other_locator), e.g., the first (0
), second (1
), third (2
) etc. element above the other element(s). Elements’ (relative) position is determined by the bottom border (y-coordinate) of their bounding box. We don’t guarantee the order of elements with the same bottom border (y-coordinate). Defaults to0
.reference_point
ReferencePoint, optional - Defines which element (located by self) is considered to be above the other element(s) (located by other_locator). Defaults to"boundary"
.
Returns:
Self
- The locator with the relation added
Examples:
and_
Logical and operator to combine multiple locators, e.g., to require an element to match multiple locators.
Arguments:
other_locator
Relatable - The locator to combine with
Returns:
Self
- The locator with the relation added
Examples:
below_of
Defines the element (located by self) to be below another element / other elements (located by other_locator).
An element A is considered to be below another element / other elements B
- if most of A (or, more specifically, A’s bounding box) is below B (or, more specifically, the bottom border of B’s bounding box) and
- if the top border of A (or, more specifically, A’s bounding box) is below the top border of B (or, more specifically, B’s bounding box).
Arguments:
other_locator
Relatable - Locator for an element / elements to relate toindex
RelationIndex, optional - Index of the element (located by self) below the other element(s) (located by other_locator), e.g., the first (0
), second (1
), third (2
) etc. element below the other element(s). Elements’ (relative) position is determined by the top border (y-coordinate) of their bounding box. We don’t guarantee the order of elements with the same top border (y-coordinate). Defaults to0
.reference_point
ReferencePoint, optional - Defines which element (located by self) is considered to be below the other element(s) (located by other_locator). Defaults to"boundary"
.
Returns:
Self
- The locator with the relation added
Examples:
containing
Defines the element (located by self) to contain another element (located by other_locator).
Arguments:
other_locator
Relatable - The locator to check if it’s contained
Returns:
Self
- The locator with the relation added
Examples:
inside_of
Defines the element (located by self) to be inside of another element (located by other_locator).
Arguments:
other_locator
Relatable - The locator to check if it contains this element
Returns:
Self
- The locator with the relation added
Examples:
left_of
Defines the element (located by self) to be left of another element / other elements (located by other_locator).
An element A is considered to be left of another element / other elements B
- if most of A (or, more specifically, A’s bounding box) is left of B (or, more specifically, the left border of B’s bounding box) and
- if the right border of A (or, more specifically, A’s bounding box) is left of the right border of B (or, more specifically, B’s bounding box).
Arguments:
other_locator
Relatable - Locator for an element / elements to relate toindex
RelationIndex, optional - Index of the element (located by self) left of the other element(s) (located by other_locator), e.g., the first (0
), second (1
), third (2
) etc. element left of the other element(s). Elements’ (relative) position is determined by the right border (x-coordinate) of their bounding box. We don’t guarantee the order of elements with the same right border (x-coordinate). Defaults to0
.reference_point
ReferencePoint, optional - Defines which element (located by self) is considered to be left of the other element(s) (located by other_locator). Defaults to"center"
.
Returns:
Self
- The locator with the relation added
Examples:
nearest_to
Defines the element (located by self) to be the nearest to another element (located by other_locator).
Arguments:
other_locator
Relatable - The locator to compare distance against
Returns:
Self
- The locator with the relation added
Examples:
or_
Logical or operator to combine multiple locators, e.g., to provide a fallback if no element is found for one of the locators.
Arguments:
other_locator
Relatable - The locator to combine with
Returns:
Self
- The locator with the relation added
Examples:
raise_if_cycle
Raises CircularDependencyError if the relations form a cycle (see Cycle (graph theory)).
askui.locators.RelationIndex
Index of the element A above, below, right or left of the other element B,
e.g., the first (0
), second (1
), third (2
) etc. element
above, below, right or left of the other element B. A’s position relative
to other elements above, below, right or left of B
(which determines its index) is determined by the relative position of its
lowest (above), highest (below), leftmost (right) or rightmost (left) point(s)
(edge of its bounding box).
Important: Which elements are counted (“indexed”) depends on the locator used, e.g.,
when using Text
only text matched is counted, and the reference_point
.
Examples:
For reference_point
"center"
, A is the first (index=0
) element above B."boundary"
, A is the second (index=1
) element above B."any"
, A is the third (index=2
) element above B.
askui.locators.Text
Locator for finding text elements by their textual content.
Arguments:
text
str | None, optional - The text content of the ui element, e.g.,'Sign up'
. Defaults toNone
. IfNone
, the locator will match any text element.match_type
TextMatchType, optional - The type of match to use. Defaults to"similar"
.similarity_threshold
int, optional - A threshold for how similar the actual text content of the ui element needs to be to the specified text to be considered a match whenmatch_type
is"similar"
. Takes values between0
and100
(inclusive, higher is more similar). Defaults to70
.
Examples:
askui.locators.TextMatchType
The type of match to use.
"similar"
uses a similarity threshold to determine if the text is a match."exact"
requires the text to be exactly the same (this is not the same as"similar"
with asimilarity_threshold
of100
as asimilarity_threshold
of100
can still allow for small differences in very long texts)."contains"
requires the text to contain (exactly) the specified text."regex"
uses a regular expression to match the text.
right_of
Defines the element (located by self) to be right of another element / other elements (located by other_locator).
An element A is considered to be right of another element / other elements B
- if most of A (or, more specifically, A’s bounding box) is right of B (or, more specifically, the right border of B’s bounding box) and
- if the left border of A (or, more specifically, A’s bounding box) is right of the left border of B (or, more specifically, B’s bounding box).
Arguments:
other_locator
Relatable - Locator for an element / elements to relate toindex
RelationIndex, optional - Index of the element (located by self) right of the other element(s) (located by other_locator), e.g., the first (0
), second (1
), third (2
) etc. element right of the other element(s). Elements’ (relative) position is determined by the left border (x-coordinate) of their bounding box. We don’t guarantee the order of elements with the same left border (x-coordinate). Defaults to0
.reference_point
ReferencePoint, optional - Defines which element (located by self) is considered to be right of the other element(s) (located by other_locator). Defaults to"center"
.
Returns:
Self
- The locator with the relation added
Examples: