ImageHandle
The project's image: channels, size, pyramid depth, and pixel access.
from plexora.api import ImageHandleImageHandle(project: Project)Every project has one -- ProjectData.image -- the one input every
plugin is guaranteed, even a "blank" project with no image file, where
the size and channel list are simply empty. Built over the project
record already in hand; nothing is read from disk until a method below
is called.
Constructor parameters
projectProjectrequiredThe project record this handle wraps. A plugin
gets one from ProjectData.image, e.g.
api.project_data(name).image, rather than constructing this
directly.
Properties
locator
locator: ResourceLocatorWhere this project's image is served from.
ResourceLocatorThe image's location -- local, or on a data node.
source
source: ImageSource | NoneThe image file's own path, format and size.
ImageSource | NoneNone for a project with no image at all. A
node-backed image still returns a source -- the channels, the
size and the pyramid depth are recorded centrally and are true
wherever the file sits -- but its path is empty; see
ImageSource.
channels
channels: list[dict]Real image channels, excluding the synthetic 'Area' channel a project only gets once it has a registered segmentation mask.
list[dict]One dict per channel, each with name, fullname
and src keys.
channel_names
channel_names: list[str]Channel names in display order.
list[str]One name per channel.
kind
kind: str | NoneThe image format, e.g. "ome_tiff", "svs".
str | NoneThe format name, or None for a project with no image.
size
size: tuple[int | None, int | None]Full-resolution image size.
tuple[int | None, int | None](width, height) in pixels.
max_level
max_level: int | NoneThe deepest pyramid level, 0 being full resolution.
int | NoneThe highest valid level for read_region.
tile_size
tile_size: tuple[int | None, int | None]The pyramid's tile size.
tuple[int | None, int | None](tile_width, tile_height) in
pixels.
is_local
is_local: boolWhether the image file is on this machine.
Worth asking before opening source.path: for a node-backed image
there is no file at any path here, and read_region is how the
pixels are reached instead.
boolTrue when the image is a local file.
is_volumetric
is_volumetric: boolWhether this image is a z-stack or time series (see volume).
boolTrue when the image has more than one plane or frame to choose between.
Methods
stats
stats(channel: str) -> dictPer-channel intensity statistics.
channelstrrequiredA channel name from channel_names.
dictIncludes the vmin/vmax display hints the viewer shows
immediately, before its full mixture-model fit lands.
quantization_window
quantization_window(channel: str) -> tupleThe byte-domain intensity window for one channel.
channelstrrequiredA channel name from channel_names.
tuple(qmin, qmax) computed from full-resolution data.
geometry
geometry() -> dictThe pyramid's shape: each level's own width and height.
Only useful for a node-backed image, where a caller cannot open the file to find out directly. For a local image, open the file instead -- the answer is the same and does not cost a request.
dictThe pyramid geometry.
ResourceNotLocalIf the image is a local file; open it directly instead of asking for its geometry.
read_region
read_region(level, box, channel_indices, max_pixels=0, view=None)Read a rectangle of pixels from one or more channels.
Works whether the image is local or on a data node, which is the point of it: a publication-resolution panel and Quick Edit's preview both read through here rather than through any tile API.
levelintrequiredThe pyramid level to read at, 0 being full resolution.
boxtuplerequired(x0, y0, x1, y1) in that level's own pixel
coordinates.
channel_indiceslist[int]requiredPositions in channels, not channel
names -- the same indexing a pyramid tile is addressed by.
max_pixelsintdefault 0Downsample so the returned array has at most this many pixels. 0 (the default) means no limit.
viewstrdefault NoneFor a z-stack or time series, which view to
read -- a plane ("z12"), a slab projection ("z4-19max",
"zmean") or a section ("xzy1200"), in that view's own
pixels (a section's rows are z). Given, it reads a local image
too. None reads the default plane of a node-backed volume and
keeps every other call exactly as it was.
tuple(pixels, clipped_box) -- the array read, and the box
that actually existed. A capture running a few pixels past the
edge of a slide is ordinary, so the returned box may be smaller
than box.
ResourceNotLocalIf the image is a local file and no view was
given; open it directly instead of reading it through this
API.
RenderErrorIf view names a view this image does not have --
any view of a planar image, or a plane past the stack's end.
volume
volume() -> dict | NoneWhat this image is as a volume, or None for a planar image.
A z-stack or time series is one object of which every plane, slab
projection and section is a view; this is its description -- extent,
spacing (with where each step came from), pyramid levels, the default
view -- the same payload the viewer reads from /volume/<name>/info.
Read from the image file (or asked of the data node holding it) once
per handle, without loading the project into the viewer.
dict | NoneThe volume's description, or None for a planar image. A node-backed volume whose node cannot describe it as one is also None; its default plane still reads.