catpy.image module

class catpy.image.BrokenSliceHandling

Bases: catpy.image.StrEnum

FILL = u'fill'

class catpy.image.DummyResponse(array)

Bases: object

class catpy.image.DummyTqdm(iterable, *args, **kwargs)

Bases: object

Methods

write

write(s)

class catpy.image.ImageFetcher(stack, output_orientation=<Orientation3D.C: u'zyx'>, preferred_mirror=None, timeout=1, cache_items=10, cache_bytes=None, broken_slice_handling=<BrokenSliceHandling.FILL: u'fill'>, cval=0, auth=None)

Bases: object

Attributes:

auth

mirror

Methods

from_catmaid(catmaid, stack_id, *args, **kwargs)	Parameters:
from_stack_info(stack_info, *args, **kwargs)	Parameters:
get(roi[, roi_mode, zoom_level, out])	Fetch image data in the ROI in the dimension order of the target orientation.
get_project_space(roi[, zoom_level, out])	Equivalent to get method with roi_mode=ROIMode.PROJECT
get_scaled_space(roi[, zoom_level, out])	Equivalent to get method with roi_mode=ROIMode.SCALED
get_stack_space(roi[, zoom_level, out])	Equivalent to get method with roi_mode=ROIMode.STACK
roi_to_scaled(roi, roi_mode, zoom_level)	Convert ROI into scaled stack space, keeping in the target dimension order.
set_fastest_mirror([reps, …])	Set the ImageFetcher to use the fastest accessible mirror.

clear_cache

auth

clear_cache()

classmethod from_catmaid(catmaid, stack_id, *args, **kwargs)

Parameters:

catmaid : catpy.AbstractCatmaidClient

stack_id : int

args, kwargs

See __init__ for arguments beyond stack

Returns:

ImageFetcher

classmethod from_stack_info(stack_info, *args, **kwargs)

Parameters:

stack_info : dict

args, kwargs

See __init__ for arguments beyond stack

Returns:

ImageFetcher

get(roi, roi_mode=<ROIMode.STACK: u'stack'>, zoom_level=0, out=None)

Fetch image data in the ROI in the dimension order of the target orientation.

ROI modes:

ROIMode.PROJECT (‘project’):

• roi is given in project space
• zoom_level specifies the zoom level of returned data
• Returned array may overflow desired ROI by < 1 scaled pixel per side
• Data will be reoriented from stack space/orientation into the target_orientation without going via project space: as such, for stacks with orientation other than ‘xy’, the output data will not be in the same orientation as the project-spaced query.

ROIMode.STACK (‘stack’):

• Default option
• roi is given in unscaled stack space (i.e. pixels at zoom level 0)
• zoom_level specifies the desired zoom level of returned data
• Returned array may overflow desired ROI by < 1 scaled pixel per side
• Equivalent to ROIMode.SCALED if zoom_level == 0

ROIMode.SCALED (‘scaled’):

• roi is given in scaled stack space at the given zoom level.
• zoom_level specifies the zoom level of ROI and returned data
• Returned array treats roi as a half-closed interval: i.e. it should have shape np.diff(roi, axis=0)

Parameters:

roi : array-like

2 x 3 array where the columns are the 3 dimensions in the target orientation, and the rows are the upper

and lower bounds of the ROI.

roi_mode : ROIMode or str

Default ROIMode.STACK

zoom_level : int

out : array-like or None

Anything with array-like __setitem__ handling (e.g. np.ndarray, np.memmap, h5py.File, z5py.File), to which the results will be written. Must have the same shape in as the ROI does in scaled pixels. If None (default), will create a new np.ndarray.

Returns:

array-like

get_project_space(roi, zoom_level=0, out=None)

Equivalent to get method with roi_mode=ROIMode.PROJECT

get_scaled_space(roi, zoom_level=0, out=None)

Equivalent to get method with roi_mode=ROIMode.SCALED

get_stack_space(roi, zoom_level=0, out=None)

Equivalent to get method with roi_mode=ROIMode.STACK

mirror

roi_to_scaled(roi, roi_mode, zoom_level)

Convert ROI into scaled stack space, keeping in the target dimension order.

Parameters:

roi : np.ndarray

ROI as 2x3 array containing half-closed bounds in the target dimension order

roi_mode : ROIMode or str

Whether the ROI is in “project”, “stack”, or “scaled” stack coordinates

zoom_level : float

The desired zoom level of the returned data

Returns:

np.ndarray

ROI as 2x3 array containing half-closed bounds in scaled stack space in the target dimension order

set_fastest_mirror(reps=1, normalise_by_tile_size=True)

Set the ImageFetcher to use the fastest accessible mirror.

Parameters:

reps : int

How many times to fetch the canary tile, for robustness

normalise_by_tile_size : bool

Whether to normalise the fetch time by the tile size used by this mirror (to get per-pixel response time)

show_progress = True

class catpy.image.Orientation3D

Bases: catpy.image.StrEnum

C = u'zyx'

FORTRAN = u'xyz'

NUMPY = u'zyx'

VIGRA = u'xyz'

XYZ = u'xyz'

ZYX = u'zyx'

class catpy.image.ProjectStack(dimension, translation, resolution, orientation, broken_slices=None, canary_location=None)

Bases: catpy.image.Stack

Methods

from_stack_info(stack_info)	Instantiate Stack from the response supplied by CATMAID’s {project_id}/stack/{stack_id}/info endpoint
get_fastest_mirror([timeout, reps, …])	Determine the fastest accessible mirror.

classmethod from_stack_info(stack_info)

Instantiate Stack from the response supplied by CATMAID’s {project_id}/stack/{stack_id}/info endpoint

Parameters:

stack_info : dict

Returns:

Stack

orientation_choices = {0: u'xy', 1: u'xz', 2: u'zy'}

class catpy.image.ROIMode

Bases: catpy.image.StrEnum

PROJECT = u'project'

SCALED = u'scaled'

STACK = u'stack'

class catpy.image.Stack(dimension, broken_slices=None, canary_location=None)

Bases: object

Methods

get_fastest_mirror([timeout, reps, …])

Determine the fastest accessible mirror.

get_fastest_mirror(timeout=1, reps=1, normalise_by_tile_size=True)

Determine the fastest accessible mirror.

Parameters:

timeout : float

Timeout in seconds for each request to the tile server

reps : int

How many times to fetch the canary tile, for robustness

normalise_by_tile_size : bool

Whether to normalise the fetch time by the tile size used by this mirror (to get per-pixel response time)

Returns:

StackMirror

class catpy.image.StackMirror(image_base, tile_height, tile_width, tile_source_type, file_extension, title=None, position=0, auth=None)

Bases: object

Methods

from_dict(d)	Instantiate StackMirror from one of the items in the ‘mirrors’ list supplied under CATMAID’s {project_id}/stack/{stack_id}/info endpoint
generate_url(tile_index)	Generate absolute URL to desired image
get_tile_index(scaled_coords[, zoom_level])	Parameters:

classmethod from_dict(d)

Instantiate StackMirror from one of the items in the ‘mirrors’ list supplied under CATMAID’s {project_id}/stack/{stack_id}/info endpoint

Parameters:

d : dict

Returns:

StackMirror

generate_url(tile_index)

Generate absolute URL to desired image

Parameters:

tile_index : TileIndex

Returns:

str

get_tile_index(scaled_coords, zoom_level=0)

Parameters:

scaled_coords : dict

zoom_level : int

Returns:

tuple of (TileIndex, dict)

Index of tile on which this pixel appears, and its offset from the top left shallow corner of that tile

class catpy.image.StrEnum

Bases: enum.Enum

class catpy.image.ThreadedImageFetcher(stack, output_orientation=<Orientation3D.C: u'zyx'>, preferred_mirror=None, timeout=1, cache_items=10, cache_bytes=None, broken_slice_handling=<BrokenSliceHandling.FILL: u'fill'>, cval=0, auth=None, threads=10)

Bases: catpy.image.ImageFetcher

Attributes:

auth

mirror

Methods

from_catmaid(catmaid, stack_id, *args, **kwargs)	Parameters:
from_stack_info(stack_info, *args, **kwargs)	Parameters:
get(roi[, roi_mode, zoom_level, out])	Fetch image data in the ROI in the dimension order of the target orientation.
get_project_space(roi[, zoom_level, out])	Equivalent to get method with roi_mode=ROIMode.PROJECT
get_scaled_space(roi[, zoom_level, out])	Equivalent to get method with roi_mode=ROIMode.SCALED
get_stack_space(roi[, zoom_level, out])	Equivalent to get method with roi_mode=ROIMode.STACK
roi_to_scaled(roi, roi_mode, zoom_level)	Convert ROI into scaled stack space, keeping in the target dimension order.
set_fastest_mirror([reps, …])	Set the ImageFetcher to use the fastest accessible mirror.

clear_cache

class catpy.image.TileCache(max_items=10, max_bytes=None)

Bases: object

Attributes:

current_bytes

Current total size, in bytes, of the cache’s values

Methods

clear

clear()

current_bytes

Current total size, in bytes, of the cache’s values

Returns:

int

class catpy.image.TileIndex(depth, row, col, zoom_level, height, width)

Bases: object

Attributes:

coords

Calculate the coordinates of the tile’s upper left corner, in scaled stack coordinates.

url_kwargs

Methods

is_comparable

comparable_keys = (u'zoom_level', u'height', u'width')

coords

Calculate the coordinates of the tile’s upper left corner, in scaled stack coordinates.

Returns:

dict

hash_keys = (u'depth', u'row', u'col', u'zoom_level', u'height', u'width')

is_comparable(other)

url_keys = (u'depth', u'row', u'col', u'zoom_level')

url_kwargs

class catpy.image.TileSourceType

Bases: enum.IntEnum

https://catmaid.readthedocs.io/en/stable/tile_sources.html

DIR_BASED = 5

DVID_IMAGEBLK = 6

DVID_IMAGETILE = 8

FILE_BASED = 1

FILE_BASED_WITH_ZOOM_DIRS = 4

FLIXSERVER = 9

H2N5_TILES = 10

HDF5 = 3

RENDER_SERVICE = 7

REQUEST_QUERY = 2

format(**kwargs)

catpy.image.as_future(item)

catpy.image.as_future_response(array)

catpy.image.dict_subtract(d1, d2)

catpy.image.fill_tiled_cuboid(min_tile_idx, max_tile_idx)

catpy.image.is_valid_format_url(format_url)

Ensure that the given URL has the required format keys for use as a format URL.

Parameters:

format_url : str

Returns:

bool

catpy.image.response_to_array(response, pil_kwargs=None)

catpy.image.response_to_array_callback(session, response)