ImageTally

ImageTally.jl is a Julia package for manually counting and categorizing objects in scientific images. It provides an interactive GUI (via GLMakie) for point-and-click counting, as well as a programmatic API for scripting, batch processing, and data export.

Typical use cases include counting insects on traps, cells in microscopy images, plants in field photographs, or any other discrete objects in high-resolution images.

Features

• Interactive GUI — left-click to place markers, right-click to delete, left-drag to move. Scroll or use the zoom buttons to zoom in/out; press R or click Reset View to restore the full image.
• Multiple tags — define up to 10 named categories (e.g., "male", "female", "egg"), each with its own color and marker shape.
• Session persistence — save and reload counting sessions as TOML files so work can be interrupted and resumed.
• CSV export — export all counted points with both relative (0–1) and pixel coordinates, plus timestamps.
• Programmatic API — create and manipulate sessions entirely in code, without opening a window.

Installation

julia> # press ]
pkg> add ImageTally

To use the interactive GUI, also install GLMakie and FileIO:

pkg> add GLMakie FileIO

Platform note: The GLMakie-based GUI extension is officially tested on Linux only. It may work on macOS and Windows, but those platforms are not covered by the CI suite.

Supported Image Formats

ImageTally supports any image format loadable by FileIO.jl and ImageIO.jl. The following formats are tested as part of the CI suite:

Format	Extension	Color	Notes
JPEG	.jpg, .jpeg	RGB	Lossy compression, most common
PNG	.png	RGB	Lossless, recommended for reproducibility
TIFF 8-bit	.tif, .tiff	RGB or Grayscale	Common in microscopy
TIFF 16-bit	.tif, .tiff	Grayscale	High dynamic range scientific images
BMP	.bmp	RGB	Uncompressed, large file size

Camera RAW formats

Camera RAW formats (.rw2, .cr2, .nef, .arw, etc.) are not directly supported. Convert to JPEG or TIFF first using:

• darktable (free, Linux/macOS/Windows)
• RawTherapee (free, Linux/macOS/Windows)
• dcraw command line tool: dcraw -T image.rw2

Large images

ImageTally has been tested with images up to 3456×5184 pixels (18 megapixels). Performance depends on your GPU. Images larger than ~8000px on either dimension may cause slow rendering.

Quick Start

GUI (interactive counting)

using GLMakie   # must be loaded before ImageTally to activate the GUI extension
using ImageTally

# Launch the counter — image dimensions are read automatically
fig, sess = launch_counter("path/to/image.jpg")

# Or resume a previous session
fig, sess = launch_counter("path/to/image.jpg"; session="image_session.toml")

Controls:

Action	Result
Left-click (empty area)	Add point with active tag
Left-drag (on a point)	Move that point
Right-click (on a point)	Delete that point
Scroll wheel	Zoom in / out
- Zoom Out / Zoom In + buttons	Zoom out / in (1.5× per click)
R key or Reset View button	Restore full-image view

Use the control panel on the right to switch the active tag, adjust marker size, and save/load/export.

Programmatic API

using ImageTally

# Create a session with custom tags
tags = [
    Tag("egg",         :red,    :circle),
    Tag("parasitized", :blue,   :utriangle),
    Tag("empty",       :gray,   :diamond),
]
sess = new_session("image.jpg", 4032, 3024; tags)

# Add points at pixel coordinates (integers or floats are both accepted)
add_point!(sess, 512, 300)         # uses the active tag ("egg")
set_active_tag!(sess, "parasitized")
add_point!(sess, 1024.0, 800.0)

# Query counts
count_by_tag(sess)   # Dict("egg" => 1, "parasitized" => 1, "empty" => 0)
total_count(sess)    # 2

# Save and reload
save_session(sess, "my_count.toml")
sess2 = load_session("my_count.toml")

# Export to CSV (id, tag, x_relative, y_relative, x_pixel, y_pixel, timestamp)
export_csv(sess, "my_count.csv")

# Human-readable summary
println(session_summary(sess))

When GLMakie is loaded, new_session can also infer image dimensions automatically:

using GLMakie, ImageTally
sess = new_session("image.jpg")                  # dimensions read from file
sess = new_session("image.jpg"; tags = tags)     # with custom tags
fig, sess = launch_counter(sess)                  # launch GUI from a pre-built session

Documentation

• Stable docs
• Development docs

How to Cite

If you use ImageTally.jl in your work, please cite using the reference given in CITATION.cff.

Contributing

If you want to make contributions of any kind, please first take a look at our contributing guide directly on GitHub or the contributing page on the website.

---

Contributors