magmap.cv.detector module

Detects features within a 3D image stack.

Prunes duplicates and verifies detections against truth sets.

ivar CONFIRMATION:

Dictionary of blob confirmation flags.

ivar OVERLAP_FACTOR:

Pixel number multiplier for overlaps between adjacent ROIs.

class magmap.cv.detector.Blobs(blobs=None, blob_matches=None, colocalizations=None, path=None, cols=None)

Bases: object

Blob storage class.

Variables:

• blob_matches – Sequence of blob matches; defaults to None.

• colocalizations – 2D Numpy array of same length as blobs with a column for each channel, where 0 = no signal and 1 = signal at the corresponding blob’s location in the given and channel; defaults to None.

• path – Path from which blobs were loaded; defaults to None.

• ver – Version number; defaults to BLOBS_NP_VER.

• roi_offset – Offset in z,y,x from ROI in which blobs were detected.

• roi_size – Size in z,y,x from ROI in which blobs were detected.

• resolutions – Physical unit resolution sizes in [[z,y,x], ...]; defaults to None.

• basename – Archive name, typically the filename without extension of the image file in which blobs were detected; defaults to None.

• scaling – Scaling factor from the blobs’ space to the main image’s space, in z,y,x; defaults to [1, 1, 1].

BLOBS_NP_VER: int = 4

Current blobs Numpy archive version number. 0: initial version 1: added resolutions, basename, offset, roi_size fields 2: added archive version number 3: added colocs 4: added “columns” for column names

class Cols(value)

Bases: Enum

Blob column names.

ABS_X = 'abs_x'

ABS_Y = 'abs_y'

ABS_Z = 'abs_z'

CHANNEL = 'channel'

CONFIRMED = 'confirmed'

RADIUS = 'radius'

TRUTH = 'truth'

X = 'x'

Y = 'y'

Z = 'z'

class Keys(value)

Bases: Enum

Numpy archive metadata keys as enumerations.

BASENAME = 'basename'

BLOBS = 'segments'

COLOCS = 'colocs'

COLS = 'columns'

RESOLUTIONS = 'resolutions'

ROI_OFFSET = 'offset'

ROI_SIZE = 'roi_size'

VER = 'ver'

classmethod blob_for_db(blob)

Convert blob to absolute coordinates.

Changes the blob format from that used within this module to that used in :module:`sqlite`, where coordinates are absolute rather than relative to the offset.

Parameters:

blob (ndarray) – Single blob.

Return type:

ndarray

Returns:

Blob in abs_z, abs_y, abs_x, rad, confirmed, truth, channel format.

property blobs: ndarray | None

Array of blobs.

classmethod blobs_in_channel(blobs, channel, return_mask=False)

Get blobs in the given channels.

Parameters:

• blobs (ndarray) – 1D blob array or 2D array of blobs.

• channel (Union[int, ndarray]) – Sequence of channels to include.

• return_mask (bool, default: False) – True to return the mask of blobs in channel.

Return type:

Union[ndarray, Tuple[ndarray, ndarray]]

Returns:

A view of the blobs in the channel, or all blobs if channel is None. If return_mask is True, also return the mask of blobs in the given channels.

property cols: Sequence[str] | None

Blob column names.

format_blobs(channel=None)

Format blobs with the full set of fields.

Blobs in MagellanMapper can be assumed to start with z, y, x, radius but should use this class’s functions to manipulate other fields to ensure that the correct columns are accessed. This function adds these fields: confirmation, truth, channel, abs z, abs y, abs x.

“Confirmed” is given as -1 = unconfirmed, 0 = incorrect, 1 = correct.

“Truth” is given as -1 = not truth, 0 = not matched, 1 = matched, where a “matched” truth blob is one that has a detected blob within a given tolerance.

Parameters:

channel (Union[int, Sequence[int], None], default: None) – Channel to set. Defaults to None, in which case the channel will not be updated.

Return type:

ndarray

Returns:

Blobs array formatted as ``[[z, y, x, radius, confirmation, truth, channel,

abs_z, abs_y, abs_x], …]``.

classmethod get_blob_abs_coords(blobs)

Get blob absolute coordinates.

Parameters:

blobs (ndarray) – 1D blob array or 2D array of blobs.

Return type:

ndarray

Returns:

Array of absolute coordinates, with dimensions corresponding to blobs.

classmethod get_blob_col(blob, col)

Get the value for the given column of a blob or blobs.

Parameters:

• blob (ndarray) – 1D blob array or 2D array of blobs.

• col (Union[int, Sequence[int]]) – Column index in blob.

Return type:

Union[int, float, ndarray]

Returns:

Single value if blob is a single blob or array of values if it is an array of blobs.

classmethod get_blob_confirmed(blob)

Get the confirmed value for blob or blobs.

Parameters:

blob (ndarray) – 1D blob array or 2D array of blobs.

Return type:

Union[int, float, ndarray]

Returns:

Single value if blob is a single blob or array of values if it is an array of blobs.

classmethod get_blob_truth(blob)

Get the truth value for blob or blobs.

Parameters:

blob (ndarray) – 1D blob array or 2D array of blobs.

Return type:

Union[int, float, ndarray]

Returns:

Single value if blob is a single blob or array of values if it is an array of blobs.

classmethod get_blobs_channel(blob)

Get the channel value for blob or blobs.

Parameters:

blob (ndarray) – 1D blob array or 2D array of blobs.

Return type:

ndarray

Returns:

Single value if blob is a single blob or array of values if it is an array of blobs.

load_blobs(path=None)

Load blobs from an archive.

Also loads associated metadata from the archive.

Parameters:

path (Optional[str], default: None) – Path to set path; defaults to None to use the existing path.

Return type:

Blobs

Returns:

Blobs object.

classmethod multiply_blob_abs_coords(blob, factor)

Multiply blob absolute coordinates.

Parameters:

• blob (ndarray) – 1D blob array or 2D array of blobs.

• factor (Union[int, float]) – Factor by which to shift the corresponding elements of blob.

Return type:

ndarray

Returns:

blob shifted in-place.

classmethod multiply_blob_rel_coords(blob, factor)

Multiply blob relative coordinates.

Parameters:

• blob (ndarray) – 1D blob array or 2D array of blobs.

• factor (Union[int, float, Sequence[Union[int, float]]]) – Factor by which to shift the corresponding elements of blob.

Return type:

ndarray

Returns:

blob shifted in-place.

classmethod remove_abs_blob_coords(blobs, remove_extra=False)

Remove blob absolute coordinate columns.

Parameters:

• blobs (ndarray) – 2D array of blobs.

• remove_extra (bool, default: False) – True to also remove any extra columns not in cols_inds; defaults to False.

Return type:

ndarray

Returns:

blob modified in-place.

classmethod replace_rel_with_abs_blob_coords(blobs)

Replace relative with absolute coordinates.

Parameters:

blobs (ndarray) – 2D array of blobs.

Return type:

ndarray

Returns:

blob modified in-place.

save_archive(to_add=None, update=False)

Save the blobs Numpy archive file to path.

Backs up any existing file before saving.

Parameters:

• to_add (dict) – Dictionary of items to add; defaults to None to use the current attributes.

• update (bool) – True to load the Numpy archive at path and update it.

Returns:

Dictionary saved to path.

Return type:

dict

classmethod set_blob_abs_coords(blobs, coords, *args, **kwargs)

Set blob absolute coordinates.

Parameters:

• blobs (ndarray) – 2D array of blobs.

• coords (Sequence[int]) – 2D array of absolute coordinates in the same order of coordinates as in blobs.

Return type:

ndarray

Returns:

Modified blobs.

classmethod set_blob_channel(blob, *args, **kwargs)

Set the channel of a blob or blobs.

Parameters:

• blob (ndarray) – 1D blob array or 2D array of blobs.

• args – Positional arguments passed to set_blob_col().

• kwargs – Named arguments passed to set_blob_col().

Return type:

ndarray

Returns:

blob after modifications.

classmethod set_blob_col(blob, col, val, mask=slice(None, None, None), **kwargs)

Set the value for the given column of a blob or blobs.

Parameters:

• blob (ndarray) – 1D blob array or 2D array of blobs.

• col (Union[int, Sequence[int]]) – Column index in blob.

• val (Union[float, Sequence[float]]) – New value. If blob is 2D, can be an array the length of blob.

• mask (Union[ndarray, IndexExpression], default: slice(None, None, None)) – Mask for the first axis; defaults to an index expression for all values. Only used for multidimensional arrays.

Return type:

ndarray

Returns:

blob after modifications.

classmethod set_blob_confirmed(blob, *args, **kwargs)

Set the confirmed flag of a blob or blobs.

Parameters:

• blob (ndarray) – 1D blob array or 2D array of blobs.

• args – Positional arguments passed to set_blob_col().

• kwargs – Named arguments passed to set_blob_col().

Return type:

ndarray

Returns:

blob after modifications.

classmethod set_blob_truth(blob, *args, **kwargs)

Set the truth flag of a blob or blobs.

Parameters:

• blob (ndarray) – 1D blob array or 2D array of blobs.

• args – Positional arguments passed to set_blob_col().

• kwargs – Named arguments passed to set_blob_col().

Return type:

ndarray

Returns:

blob after modifications.

classmethod shift_blob_abs_coords(blob, offset)

Shift blob absolute coordinates by offset.

Parameters:

• blob (ndarray) – 1D blob array or 2D array of blobs.

• offset (Sequence[int]) – Sequence of coordinates by which to shift the corresponding elements of blob.

Return type:

ndarray

Returns:

blob shifted in-place.

classmethod shift_blob_rel_coords(blob, offset)

Shift blob relative coordinates by offset.

Parameters:

• blob (ndarray) – 1D blob array or 2D array of blobs.

• offset (Sequence[int]) – Sequence of coordinates by which to shift the corresponding elements of blob.

Return type:

ndarray

Returns:

blob shifted in-place.

classmethod shift_blobs(blob, cols, fn, vals, to_int=False)

Shift blob columns with a function.

Parameters:

• blob (ndarray) – 1D blob array or 2D array of blobs.

• cols (Union[int, Sequence[int]]) – Column(s) to modify.

• fn (Callable) – Function that takes a subset of blob and vals.

• vals (Union[int, float, Sequence[Union[int, float]]]) – Values by which to shift the corresponding elements of blob.

• to_int (bool, default: False) – True to convert the shifted elements to int; defaults to False.

Return type:

ndarray

Returns:

blob shifted in-place.

classmethod show_blobs_per_channel(blobs)

Show the number of blobs in each channel.

Parameters:

blobs (ndarray) – 1D blob array or 2D array of blobs.

magmap.cv.detector.calc_overlap(factor=None)

Calculate overlap based on scaling factor and a factor.

Parameters:

factor (Optional[int], default: None) – Overlap factor; defaults to None to use :const:OVERLAP_FACTOR

Returns:

Overlap as an array in the same shape and order as in :attr:resolutions.

magmap.cv.detector.calc_scaling_factor()

Calculates the tolerance based on the resolutions, using the first resolution.

Returns:

Array of tolerance values in same shape as the first resolution.

:raises AttributeError` if the :attr:config.resolutions is None or ha: :raises less than one element.:

magmap.cv.detector.detect_blobs(roi, channel, exclude_border=None)

Detects objects using 3D blob detection technique.

Parameters:

• roi (ndarray) – Region of interest to segment.

• channel (Sequence[int]) – Sequence of channels to select, which can be None to indicate all channels.

• exclude_border (Optional[Sequence[int]], default: None) – Sequence of border pixels in x,y,z to exclude; defaults to None.

Return type:

Optional[ndarray]

Returns:

Array of detected blobs, each given as z, row, column, radius, confirmation.

magmap.cv.detector.get_blobs_in_roi(blobs, offset, size, margin=(0, 0, 0), reverse=True)

Get blobs within an ROI based on offset and size.

Note that dimensions are in x,y,z for natural ordering but may change for consistency with z,y,x ordering used throughout MagellanMapper.

Parameters:

• blobs (ndarray) – The blobs to retrieve, given as 2D array of [n, [z, row, column, radius, ...]].

• offset (Sequence[int]) – Offset coordinates in x,y,z.

• size (Sequence[int]) – Size of ROI in x,y,z.

• margin (Sequence[int], default: (0, 0, 0)) – Additional space outside the ROI to include in x,y,z.

• reverse (bool, default: True) – True to reverse the order of offset and size, assuming that they are in x,y,z rather than z,y,x order. Defaults to True for backward compatibility with the ROI convention used here.

Returns:

• ``segs_all`: Blobs within the ROI

• mask: the mask used to retrieve these blobs

Return type:

Tuple of

magmap.cv.detector.get_blobs_interior(blobs, shape, pad_start, pad_end)

Get blobs within the interior of a region based on padding.

Parameters:

• blobs – The blobs to retrieve, given as 2D array of [n, [z, row, column, radius, ...]].

• shape – Shape of the region in z,y,x.

• pad_start – Offset of interior region in z,y,x to include blobs.

• pad_end – End offset in z,y,x.

Returns:

Blobs within the given interior.

magmap.cv.detector.meas_pruning_ratio(num_blobs_orig, num_blobs_after_pruning, num_blobs_next)

Measure blob pruning ratio.

Parameters:

• num_blobs_orig – Number of original blobs, before pruning.

• num_blobs_after_pruning – Number of blobs after pruning.

• num_blobs_next – Number of a blobs in an adjacent segment, presumably of similar size as that of the original blobs.

Returns:

Pruning ratios as a tuple of the original number of blobs, blobs after pruning to original, and blobs after pruning to the next region.

magmap.cv.detector.remove_close_blobs(blobs, blobs_master, tol, chunk_size=1000)

Removes blobs that are close to one another.

Parameters:

• blobs (ndarray) – The blobs to be checked for closeness and pruning, given as 2D array of [n, [z, row, column, …]].

• blobs_master (ndarray) – The list by which to check for close blobs, in the same format as blobs.

• tol (float) – Tolerance to check for closeness, given in the same format as region. Blobs that are equal to or less than the absolute difference for all corresponding parameters will be pruned in the returned array.

• chunk_size (int, default: 1000) – Max size along first dimension for each blob array to minimize memory consumption; defaults to 1000.

Returns:

• pruned: blobs array after pruning

• blobs_master`: blobs with absolute coordinates updated with the average of any corresponding duplicates

Return type:

Tuple of

magmap.cv.detector.remove_close_blobs_within_array(blobs, region, tol)

Removes close blobs within a given array.

Uses remove_close_blobs() to detect blobs close to one another inside the master array.

Parameters:

• blobs – The blobs to add, given as 2D array of [n, [z, row, column, radius]].

• region – Slice within each blob to check, such as slice(0, 2) to check for (z, row, column).

• tol – Tolerance to check for closeness, given in the same format as region. Blobs that are equal to or less than the the absolute difference for all corresponding parameters will be pruned in the returned array.

Returns:

The blobs array without blobs falling inside the tolerance range.

magmap.cv.detector.remove_close_blobs_within_sorted_array(blobs, tol)

Removes close blobs within a given array, first sorting the array by z, y, x.

Parameters:

• blobs – The blobs to add, given as 2D array of [n, [z, row, column, radius]].

• tol – Tolerance to check for closeness, given in the same format as region. Blobs that are equal to or less than the the absolute difference for all corresponding parameters will be pruned in the returned array.

Returns:

Tuple of all blobs, a blobs array without blobs falling inside the tolerance range.

magmap.cv.detector.remove_duplicate_blobs(blobs, region)

Removes duplicate blobs.

Parameters:

• blobs – The blobs, given as 2D array of [n, [z, row, column, radius]].

• region – Slice within each blob to check, such as slice(0, 2) to check for (z, row, column).

Returns:

The blobs array with only unique elements.

magmap.cv.detector.show_blob_surroundings(blobs, roi, padding=1)

magmap.cv.detector.sort_blobs(blobs)

Sort blobs by their coordinates in priority of z,y,x.

Parameters:

blobs – Blobs as a 2D array of [n, [z, row, column, …]].

Returns:

Tuple of the sorted blobs as a new array and an array of sorting indices.