Reference

Valid GLMakie marker symbols accepted by ImageTally.

CountPoint

Represents a single counted object in the image.

Fields

• id::Int: Unique identifier
• x::Float64: Relative x position (0.0 to 1.0)
• y::Float64: Relative y position (0.0 to 1.0)
• tag::String: Name of the associated Tag
• `timestamp::DateTime

CountSession

Holds all state for a single counting session.

Fields

• image_path::String: Path to the image file
• image_width::Int: Original image width in pixels
• image_height::Int: Original image height in pixels
• tags::Vector{Tag}: Available counting categories
• points::Vector{CountPoint}: All counted points
• next_id::Int: Counter for generating unique point IDs
• active_tag::String: Currently selected tag name
• marker_size::Float64: Display size of markers

Tag

Represents a user-defined counting category with visual properties.

Fields

• name::String: Display name (e.g. "male", "female", "egg"). Must not be empty.
• color::Symbol: Marker color (e.g. :red, :blue, :green). GLMakie accepts any named color; commonly used values include :red, :blue, :green, :orange, :purple, :cyan, :magenta, :yellow, :black, :white, :gray.
• marker::Symbol: Marker shape (e.g. :circle, :utriangle). Known supported markers are (:circle, :utriangle, :dtriangle, :rect, :diamond, :xcross, :cross, :pentagon). A warning is issued for unrecognised symbols.

Throws

• ArgumentError if name is empty.

add_point!(session, x_px, y_px) -> CountPoint

Add a new point at the given pixel coordinates using the active tag. Coordinates are converted to relative and clamped to valid range. Both integer and floating-point coordinates are accepted.

Examples

add_point!(session, 1728.0, 2592.0)
add_point!(session, 1728, 2592)

add_tag!(session, tag) -> Tag

Add a new tag to the session. Throws ArgumentError if a tag with the same name already exists or if the maximum number of tags is reached.

Examples

add_tag!(session, Tag("juvenile", :green, :diamond))

clamp_to_image(x_rel, y_rel) -> Tuple{Float64, Float64}

Clamp relative coordinates to valid image range (0.0 to 1.0). Handles clicks slightly outside the image boundary.

count_by_tag(session) -> Dict{String, Int}

Return a dictionary with the count of points for each tag.

Examples

count_by_tag(session)  # Dict("male" => 5, "female" => 3)

default_tags() -> Vector{Tag}

Return a default set of two tags to use when no tags are specified.

delete_point!(session, id) -> Bool

Delete the point with the given id. Returns true if found and deleted, false if no point with that id exists.

Examples

delete_point!(session, 1)

export_csv(session, path) -> Nothing

Export the counted points to a CSV file at path. Each row represents one counted point with its relative coordinates, pixel coordinates, tag, and timestamp.

The CSV includes both relative (0.0-1.0) and absolute pixel coordinates so the data is useful regardless of how the image is displayed.

Examples

export_csv(session, "my_count.csv")

find_nearest_point(session, x_px, y_px; threshold=50.0) -> Union{CountPoint, Nothing}

Find the nearest point to the given pixel coordinates within the threshold distance. Returns nothing if no point is within the threshold.

Examples

point = find_nearest_point(session, 1728.0, 2592.0)

get_tag(session, tag_name) -> Union{Tag, Nothing}

Return the Tag with the given name, or nothing if it doesn't exist.

Examples

tag = get_tag(session, "male")

has_tag(session, tag_name) -> Bool

Return true if a tag with the given name exists in the session.

Examples

has_tag(session, "male")  # true or false

launch_counter(args...; kwargs...)

Launch the ImageTally graphical counting interface. Requires GLMakie to be loaded first:

using GLMakie
using ImageTally
launch_counter("path/to/image.jpg")

load_session(path) -> CountSession

Load a CountSession from a TOML file previously saved with save_session.

Examples

session = load_session("my_count.toml")

move_point!(session, id, x_px, y_px) -> Bool

Move the point with the given id to new pixel coordinates. Returns true if found and moved, false if no point with that id exists. Both integer and floating-point coordinates are accepted.

Examples

move_point!(session, 1, 1800.0, 2600.0)
move_point!(session, 1, 1800, 2600)

new_session(image_path, width, height; tags=default_tags()) -> CountSession

Create a new counting session for the given image.

Examples

session = new_session("moths.jpg", 3456, 5184)
session = new_session("moths.jpg", 3456, 5184; tags=[Tag("male", :blue, :circle), Tag("female", :red, :utriangle)])

Throws

• ArgumentError if image_path is empty.
• ArgumentError if width or height is not positive.
• ArgumentError if tags is empty or exceeds MAX_TAGS.

pixel_to_relative(x_px, y_px, width, height) -> Tuple{Float64, Float64}

Convert pixel coordinates to relative coordinates (0.0 to 1.0).

Examples

pixel_to_relative(1728, 2592, 3456, 5184)  # (0.5, 0.5)

relative_to_pixel(x_rel, y_rel, width, height) -> Tuple{Int, Int}

Convert relative coordinates (0.0 to 1.0) to pixel coordinates.

Examples

relative_to_pixel(0.5, 0.5, 3456, 5184)  # (1728, 2592)

remove_tag!(session, tag_name) -> Bool

Remove the tag with the given name. Returns false if the tag doesn't exist. Throws ArgumentError if points exist with this tag — delete or retag those points first. Automatically switches active tag if the removed tag was active.

Examples

remove_tag!(session, "juvenile")

save_session(session, path) -> Nothing

Save a CountSession to a TOML file at path. The session can be reloaded with load_session. The image file is not saved — only its path and dimensions are recorded.

Examples

save_session(session, "my_count.toml")

session_summary(session) -> String

Return a human-readable summary of the session as a string.

Examples

println(session_summary(session))

set_active_tag!(session, tag_name) -> Nothing

Set the active tag by name. Throws ArgumentError if tag doesn't exist.

Examples

set_active_tag!(session, "female")

set_marker_size!(session, size) -> Nothing

Set the global marker display size. Must be positive. Both integer and floating-point values are accepted. A warning is issued for sizes above 200, which are unusually large and may obscure the image.

Examples

set_marker_size!(session, 20.0)
set_marker_size!(session, 20)

Throws

• ArgumentError if size is not positive.

total_count(session) -> Int

Return the total number of counted points across all tags.

Examples

total_count(session)  # 8