ScaleBar.jl

The ScaleBar package is a tool for adding scale bars to images, particularly useful for scientific and microscopy applications. It provides a simple, consistent API for adding scale bars with customizable positions, sizes, and colors.

Overview

Scale bars are essential for providing spatial context in scientific images, especially in microscopy where the actual size of objects isn't immediately apparent. ScaleBar.jl makes it easy to add professional-looking scale bars to your images.

Key features:

Add scale bars with physical units (μm, nm, etc.) based on pixel size
Add scale bars with specific pixel dimensions
Position scale bars in any corner of the image
Customize size, color, and padding
Both in-place and non-destructive operations

Basic Usage

Physical Scale Bars

To add a scale bar based on physical units:

using Images, ScaleBar

# Create a test image with gray background for better visibility
img = RGB.(fill(0.5, 512, 512))

# Add a scale bar representing 10μm (assuming 0.1μm per pixel)
scalebar!(img, 0.1, 10; units="μm")

Pixel-Based Scale Bars

To add a scale bar with pixel dimensions:

using Images, ScaleBar

# Create a test image with gray background for better visibility
img = RGB.(fill(0.5, 512, 512))

# Add a 50-pixel scale bar
scalebar!(img, 50)

Different Image Types

ScaleBar.jl works with various image types:

RGB Images

# RGB image with gray background
img_rgb = RGB.(fill(0.5, 512, 512))
scalebar!(img_rgb, 0.1, 10; units="μm")

Grayscale Images

# Grayscale image
img_gray = Gray.(fill(0.5, 512, 512))
scalebar!(img_gray, 0.1, 10; units="μm")

Float64 Arrays with Values > 1.0

For Float64 arrays with values greater than 1.0, the scale bar is added using the maximum value:

# Float64 array with values > 1.0
img_float = rand(512, 512) * 100.0  # Values between 0 and 100
scalebar!(img_float, 0.1, 10; units="μm")
# Scale bar will be drawn with the maximum value in the array
# When saving to images, normalize to [0,1] range (e.g., img ./= maximum(img))

Positioning

You can position the scale bar at any of the four corners of the image using CairoMakie-style positioning symbols:

# Top left
scalebar!(img, 50; position=:tl)

# Top right
scalebar!(img, 50; position=:tr)

# Bottom left
scalebar!(img, 50; position=:bl)

# Bottom right (default)
scalebar!(img, 50; position=:br)

Non-destructive Scale Bar Addition

The non-mutating scalebar function returns more than just the image - it provides a named tuple with information about the scale bar:

# With physical units
result = scalebar(img, 0.1; units="μm")
img_with_bar = result.image                 # The new image with a scale bar
physical_length = result.physical_length    # The physical length of the scale bar
pixel_length = result.pixel_length          # The length in pixels
units = result.units                        # The units used

# With pixel dimensions
result = scalebar(img; length=50)
img_with_bar = result.image                 # The new image with a scale bar
pixel_length = result.pixel_length          # The length of the scale bar in pixels

# You can also use destructuring syntax
(; image, physical_length, pixel_length, units) = scalebar(img, 0.1, units="μm")

API Documentation

For a comprehensive overview of the API, use the help mode on api_overview:

?ScaleBar.api_overview

Or access the complete API documentation programmatically:

docs = ScaleBar.api_overview()

API Reference

ScaleBar.scalebar! — Function

scalebar!(img, pixel_size, physical_length; kwargs...)

Add a scale bar to an image in-place, using physical units.

Arguments

img::AbstractArray : Input image
pixel_size::Real : Size of each pixel in physical units (e.g., nm, μm)
physical_length::Real : Length of the scale bar in physical units

Keyword Arguments

position::Symbol : Position of the scale bar (`:tl`, `:tr`, `:bl`, `:br`), default: `:br`
width::Integer : Width of the scale bar in pixels, default: auto-calculated
padding::Integer : Padding from the edge of the image in pixels, default: 10
color::Symbol : Color of the scale bar (`:white` or `:black`), default: `:white`
units::String : Units for the physical length (e.g., "nm", "μm"), default: ""

Returns

Nothing, modifies img in-place

Examples

using Images, ScaleBar

# Create a test image with gray background for better visibility
img = RGB.(fill(0.5, 512, 512))

# Add a scale bar representing 10μm (assuming 0.1μm per pixel)
scalebar!(img, 0.1, 10; position=:br, units="μm")

source

scalebar!(img, length; kwargs...)

Add a scale bar to an image in-place, specifying dimensions in pixels.

Arguments

img::AbstractArray : Input image
length::Integer : Length of the scale bar in pixels

Keyword Arguments

position::Symbol : Position of the scale bar (`:tl`, `:tr`, `:bl`, `:br`), default: `:br`
width::Integer : Width of the scale bar in pixels, default: auto-calculated
padding::Integer : Padding from the edge of the image in pixels, default: 10
color::Symbol : Color of the scale bar (`:white` or `:black`), default: `:white`

Returns

Nothing, modifies img in-place

Examples

using Images, ScaleBar

# Create a test image with gray background for better visibility
img = RGB.(fill(0.5, 512, 512))

# Add a 50-pixel scale bar
scalebar!(img, 50; position=:br)

source

ScaleBar.scalebar — Function

scalebar(img, pixel_size; physical_length=nothing, kwargs...)

Create a new image with a scale bar, using physical units.

Arguments

img::AbstractArray : Input image
pixel_size::Real : Size of each pixel in physical units (e.g., nm, μm)

Keyword Arguments

physical_length::Union{Real, Nothing} : Length of the scale bar in physical units, default: auto-calculated
position::Symbol : Position of the scale bar (`:tl`, `:tr`, `:bl`, `:br`), default: `:br`
width::Union{Integer, Nothing} : Width of the scale bar in pixels, default: auto-calculated
padding::Integer : Padding from the edge of the image in pixels, default: 10
color::Symbol : Color of the scale bar (`:white` or `:black`), default: `:white`
units::String : Units for the physical length (e.g., "nm", "μm"), default: ""

Returns

A named tuple containing:
- image: A new image with the scale bar added
- physical_length: The physical length of the scale bar
- pixel_length: The length of the scale bar in pixels
- units: The units of the physical length

Examples

using Images, ScaleBar

# Create a test image with gray background for better visibility
img = RGB.(fill(0.5, 512, 512))

# Add a scale bar with auto-calculated length (assuming 0.1μm per pixel)
result = scalebar(img, 0.1; position=:br, units="μm")
img_with_bar1 = result.image
physical_length = result.physical_length  # The physical length that was used
pixel_length = result.pixel_length        # The length in pixels
units = result.units                      # The units of the physical length

# Add a scale bar with explicit length of 10μm
result = scalebar(img, 0.1; physical_length=10, position=:br, units="μm")
img_with_bar2 = result.image

# Using destructuring syntax
(; image, physical_length, pixel_length, units) = scalebar(img, 0.1; position=:br, units="μm")

source

scalebar(img; length=nothing, kwargs...)

Create a new image with a scale bar, specifying dimensions in pixels.

Arguments

img::AbstractArray : Input image

Keyword Arguments

length::Union{Integer, Nothing} : Length of the scale bar in pixels, default: auto-calculated
position::Symbol : Position of the scale bar (`:tl`, `:tr`, `:bl`, `:br`), default: `:br`
width::Union{Integer, Nothing} : Width of the scale bar in pixels, default: auto-calculated
padding::Integer : Padding from the edge of the image in pixels, default: 10
color::Symbol : Color of the scale bar (`:white` or `:black`), default: `:white`

Returns

A named tuple containing:
- image: A new image with the scale bar added
- pixel_length: The length of the scale bar in pixels

Examples

using Images, ScaleBar

# Create a test image with gray background for better visibility
img = RGB.(fill(0.5, 512, 512))

# Add a scale bar with auto-calculated length
result = scalebar(img; position=:br)
img_with_bar1 = result.image
pixel_length = result.pixel_length  # The length in pixels that was used

# Add a 50-pixel scale bar with explicit length
result = scalebar(img; length=50, position=:br)
img_with_bar2 = result.image

# Using destructuring syntax
(; image, pixel_length) = scalebar(img; position=:br)

source