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
microns = scan.distances * ds.pixel_size.to("um").value

`nimbusimage.images.ImageAccessor`

Access images for a dataset.

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

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

Always returns a squeezed 2D array.

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`

Returns:

Type	Description
`ndarray`	2D numpy array.

`get_all_channels(xy=0, z=0, time=0)`

Get all channels at one location as a list of 2D arrays.

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

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'`

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)`

Get a composite RGB image merging visible channels.

Uses layer settings from ds.collections.layers for contrast and color.

Parameters:

Name	Type	Description	Default
`mode`	`str`	Blend mode ('lighten' default).	`'lighten'`
`dtype`	`str \| None`	Output dtype. None = match source. 'float64' = [0,1]. 'uint8' = [0,255].	`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.