Images

Image retrieval, stacking, compositing, and line-scan intensity profiles.

Line scan example

Measure an intensity profile along a line — the same computation as the viewer's line scan tool. Works with an anonymous connection on public datasets.

import nimbusimage as ni

client = ni.connect("http://localhost:8080/api/v1", anonymous=True)
ds = client.dataset("<public-dataset-id>")

# Straight segment (two points) or a freehand path (more points),
# in image pixel coordinates
scan = ds.images.line_scan([(120, 512), (520, 512)], channel=0, time=0)

scan.distances   # (N,) distance from start, in pixels
scan.values      # (N,) intensities; NaN where the line leaves the image
scan.points      # (N, 2) sampled (x, y) coordinates

# Distances in physical units
pixel_size = ds.pixel_size  # None when the size is unknown
if pixel_size is not None:
    microns = scan.distances * pixel_size.to("um").value

nimbusimage.images.ImageAccessor

Access images for a dataset.

get(xy=0, z=0, time=0, channel=0, crop=None, max_size=None)

Get a single image frame as a 2D numpy array.

Always returns a 2D (height, width) array for a single-band image, including for a one-pixel-high or -wide crop.

Parameters:

Name	Type	Description	Default
xy, z, time, channel		Coordinates.	required
crop	tuple[float, float, float, float] | None	Optional (left, top, right, bottom) crop region.	None
max_size	int | None	Optional longest side of the result, in pixels. The server downsamples (from the image pyramid), so a large slide is never transferred at full resolution. Never upsamples.	None

Returns:

Type	Description
ndarray	2D numpy array.

get_all_channels(xy=0, z=0, time=0, max_size=None)

Get all channels at one location as a list of 2D arrays. max_size: see get().

get_stack(xy=0, z=0, time=0, channel=0, axis='z', max_size=None)

Get a stack along one axis as a 3D array.

Parameters:

Name	Type	Description	Default
axis	str	'z' or 'time'. The other coordinates are fixed.	'z'
max_size	int | None	Optional longest side of each plane; see get().	None

Returns:

Type	Description
ndarray	3D numpy array: (N, H, W) where N is the axis size.

get_composite(xy=0, z=0, time=0, mode='lighten', dtype=None, max_size=None, crop=None)

Get an RGB composite of the visible layers, as the app draws it.

Follows the caller's layer settings (ds.collections): color, visibility, contrast with their per-view overrides, and each layer's XY/Z/time slice setting (current, constant, offset, or max-merge, a maximum projection along the axis). A layer whose slice falls outside the dataset, or whose channel has no frame here, is left out, as in the app.

Contrast follows the app (toStyle in src/store/images.ts): absolute black/white points are raw intensities; percentile points are percents of the frame histogram's min..max range (the same histogram request the app makes), not quantiles.

Parameters:

Name	Type	Description	Default
mode	str	'lighten' (default, per-channel maximum, as in the app) or 'add'.	'lighten'
dtype	str | None	Output dtype. None = match source. 'float64' = [0,1]. 'uint8' = [0,255].	None
max_size	int | None	Optional longest side of the result, in pixels; the server downsamples. See get().	None
crop	tuple[float, float, float, float] | None	Optional (left, top, right, bottom) region, in full resolution pixels.	None

Returns:

Type	Description
ndarray	(H, W, 3) numpy array.

line_scan(points, xy=0, z=0, time=0, channel=0, max_samples=2000, max_region_dim=2048)

Measure the intensity profile along a polyline.

Matches the frontend line scan tool: the polyline is resampled at roughly one sample per pixel of arc length and intensities are bilinearly interpolated from the pixels around each sample.

Parameters:

Name	Type	Description	Default
points	Sequence[tuple[float, float]] | ndarray	Polyline vertices as (x, y) pairs in image pixel coordinates. Two points measure a straight segment; more points a freehand path.	required
xy, z, time, channel		Frame coordinates.	required
max_samples	int	Cap on the number of samples along the line.	2000
max_region_dim	int	Pixel regions larger than this per side are downsampled by the server before sampling. Bounds the transfer size for lines spanning huge images.	2048

Returns:

Type	Description
LineScanResult	LineScanResult with distances (px), values (NaN outside the
LineScanResult	image), and the sampled (x, y) points. Convert distances to
LineScanResult	physical units with ds.pixel_size.

Raises:

Type	Description
ValueError	For fewer than 2 vertices or a zero-length line.

iter_frames()

Iterate over all frames in the dataset.

Yields:

Type	Description
tuple[FrameInfo, ndarray]	(FrameInfo, 2D numpy array) tuples.

new_writer(copy_metadata=True)

Create an ImageWriter for writing processed images.

Requires the [worker] extra (large_image).

nimbusimage.images.LineScanResult

Bases: NamedTuple

Intensity profile along a polyline.

Attributes:

Name	Type	Description
distances	ndarray	(N,) distances of each sample from the start of the line, in pixels.
values	ndarray	(N,) float64 intensities, bilinearly interpolated. NaN for samples outside the image.
points	ndarray	(N, 2) x, y image coordinates of each sample.

nimbusimage.images.ImageWriter

Write processed images back to the dataset.

Requires the [worker] extra (large_image package). Can be used as a context manager or explicitly.

add_frame(image, **kwargs)

Add a frame to the output.

kwargs should include c, z, t, xy for frame positioning.

set_metadata(**kwargs)

Set metadata that will be added to the uploaded item.

write(filename='output.tiff')

Write the TIFF and upload to the dataset folder.