ximage.patch package

ximage.patch package#

Submodules#

ximage.patch.checks module#

Checks for patch extraction function arguments.

ximage.patch.checks.check_buffer(buffer, dims, shape)[source][source]#

Check the validity of the buffer argument based on the array shape.

Parameters:

  • buffer ((int, float, list, tuple or dict)) – The size of the buffer to apply to the array. If int or float, equal buffer is set on each dimension of the array. If list or tuple, the length must match the number of dimensions of the array. If a dict, it must have has keys all array dimensions.

  • dims (tuple) – The names of the array dimensions.

  • shape (tuple) – The shape of the array.

Returns:

buffer – The buffer to apply on each dimension.

Return type:

dict

ximage.patch.checks.check_kernel_size(kernel_size, dims, shape)[source][source]#

Check the validity of the kernel_size argument based on the array shape.

Parameters:

  • kernel_size ((int, list, tuple, dict)) – The size of the kernel to extract from the array. If int or float, the kernel is a hypercube of size patch_size across all dimensions. If list or tuple, the length must match the number of dimensions of the array. If a dict, it must have has keys all array dimensions. The value -1 can be used to specify the full array dimension shape. Otherwise, only positive integers values (>1) are accepted.

  • dims (tuple) – The names of the array dimensions.

  • shape (tuple) – The shape of the array.

Returns:

kernel_size – The shape of the kernel.

Return type:

dict

ximage.patch.checks.check_padding(padding, dims, shape)[source][source]#

Check the validity of the padding argument based on the array shape.

Parameters:

  • padding ((int, float, list, tuple or dict)) – The size of the padding to apply to the array. If None, zero padding is assumed. If int or float, equal padding is set on each dimension of the array. If list or tuple, the length must match the number of dimensions of the array. If a dict, it must have has keys all array dimensions.

  • dims (tuple) – The names of the array dimensions.

  • shape (tuple) – The shape of the array.

Returns:

padding – The padding to apply on each dimension.

Return type:

dict

ximage.patch.checks.check_partitioning_method(partitioning_method)[source][source]#

Check partitioning method.

ximage.patch.checks.check_patch_size(patch_size, dims, shape)[source][source]#

Check the validity of the patch_size argument based on the array shape.

Parameters:

  • patch_size ((int, list, tuple, dict)) – The size of the patch to extract from the array. If int, the patch is a hypercube of size patch_size across all dimensions. If list or tuple, the length must match the number of dimensions of the array. If a dict, it must have as keys all array dimensions. The value -1 can be used to specify the full array dimension shape. Otherwise, only positive integers values (>1) are accepted.

  • dims (tuple) – The names of the array dimensions.

  • shape (tuple) – The shape of the array.

Returns:

patch_size – The shape of the patch.

Return type:

dict

ximage.patch.checks.check_stride(stride, dims, shape, partitioning_method)[source][source]#

Check the validity of the stride argument based on the array shape.

Parameters:

  • stride ((None, int, float, list, tuple, dict)) – The size of the stride to apply to the array. If None, no striding is assumed. If int or float, equal stride is set on each dimension of the array. If list or tuple, the length must match the number of dimensions of the array. If a dict, it must have has keys all array dimensions.

  • dims (tuple) – The names of the array dimensions.

  • shape (tuple) – The shape of the array.

  • partitioning_method ((None, str)) – The optional partitioning method (tiling or sliding) to use.

Returns:

stride – The stride to apply on each dimension.

Return type:

dict

ximage.patch.labels_patch module#

Functions to extract patch around labels.

ximage.patch.labels_patch.find_point(arr, centered_on: str | Callable = 'max')[source][source]#

Find a specific point coordinate of the array.

If the coordinate can’t be find, return None.

ximage.patch.labels_patch.get_patches_from_labels(xr_obj, label_name, patch_size, variable=None, n_patches=None, n_labels=None, labels_id=None, highlight_label_id=True, centered_on='max', padding=0, n_patches_per_label=None, n_patches_per_partition=1, partitioning_method=None, n_partitions_per_label=None, kernel_size=None, buffer=0, stride=None, include_last=True, ensure_slice_size=True, debug=False, verbose=False)[source][source]#

Routines to extract patches around labels.

Create a generator extracting (from a prelabeled xarray.Dataset) a patch around:

  • a label point

  • a label bounding box

If centered_on is specified, output patches are guaranteed to have equal shape ! If centered_on is not specified, output patches are guaranteed to have only have a minimum shape !

If you want to extract the patch around the label bounding box, centered_on must not be specified.

If you want to extract the patch around a label point, the centered_on method must be specified. If the identified point is close to an array boundary, the patch is expanded toward the valid directions.

Tiling or sliding enables to split/slide over each label and extract multiple patch for each tile.

tiling=True - centered_on = "centroid" (tiling around labels bbox) - centered_on = "center_of_mass" (better coverage around label)

sliding=True - centered_on = "center_of_mass" (better coverage around label) (further data coverage)

Only one parameter between n_patches and labels_id can be specified.

Parameters:

  • xr_obj (xarray.Dataset) – xarray.Dataset with a label array named label_name.

  • label_name (str) – Name of the variable/coordinate representing the label array.

  • patch_size (int or tuple) – The dimensions of the n-dimensional patch to extract. Only positive values (>1) are allowed. The value -1 can be used to specify the full array dimension shape. If the centered_on method is not 'label_bbox', all output patches are ensured to have the same shape. Otherwise, if centered_on='label_bbox', the patch_size argument defines defined the minimum n-dimensional shape of the output patches. If int, the value is applied to all label array dimensions. If list or tuple, the length must match the number of dimensions of the array. If a dict, the dictionary must have has keys the label array dimensions.

  • n_patches (int, optional) – Maximum number of patches to extract. The default (None) enable to extract all available patches allowed by the specified patch extraction criteria.

  • labels_id (list, optional) – List of labels for which to extract the patch. If None, it extracts the patches by label order (1, 2, 3, ...) The default is None.

  • n_labels (int, optional) – The number of labels for which extract patches. If None (the default), it extract patches for all labels. This argument can be specified only if labels_id is unspecified !

  • highlight_label_id (bool, optional) – If True, the label_name array of each patch is modified to contain only the label_id used to select the patch.

  • variable (str, optional) – Dataset variable to use to identify the patch center when centered_on is defined. This is required only for centered_on='max', centered_on='min' or the custom function.

  • centered_on (str or callable, optional) –

    The centered_on method characterize the point around which the patch is extracted. Valid pre-implemented centered_on methods are 'label_bbox', 'max', 'min', 'centroid', 'center_of_mass', 'random'. The default method is 'max'.

    If label_bbox it extract the patches around the (padded) bounding box of the label. If label_bbox, the output patch sizes are only ensured to have a minimum patch_size, and will likely be of different size. Otherwise, the other methods guarantee that the output patches have a common shape.

    If centered_on is 'max', 'min' or a custom function, the variable argument must be specified. If centered_on is a custom function, it must: - return None if all array values are non-finite (i.e np.nan) - return a tuple with same length as the array shape.

  • padding (int, tuple or dict, optional) – The padding to apply in each direction around a label prior to partitioning (tiling/sliding) or direct patch extraction. The default, 0, applies 0 padding in every dimension. Negative padding values are allowed ! If int, the value is applied to all label array dimensions. If list or tuple, the length must match the number of dimensions of the array. If a dict, the dictionary must have has keys the label array dimensions.

  • n_patches_per_label (int, optional) – The maximum number of patches to extract for each label. The default (None) enables to extract all the available patches per label. If specified, n_patches_per_label must be larger than n_patches_per_partition !

  • n_patches_per_partition – The maximum number of patches to extract from each label partition. The default values is 1. This method can be specified only if centered_on='random' or a callable.

  • int – The maximum number of patches to extract from each label partition. The default values is 1. This method can be specified only if centered_on='random' or a callable.

  • optional – The maximum number of patches to extract from each label partition. The default values is 1. This method can be specified only if centered_on='random' or a callable.

  • partitioning_method (str) – Whether to retrieve 'tiling' or 'sliding' slices. If 'tiling', partition start slices are separated by stride + kernel_size. If 'sliding', partition start slices are separated by stride.

  • n_partitions_per_label (int, optional) – The maximum number of partitions to extract for each label. The default (None) enables to extract all the available partitions per label.

  • stride (int, tuple or dict, optional) – If partitioning_method = 'sliding', default stride is set to 1. If partitioning_method = 'tiling', default stride is set to 0. Step size between slices. When partitioning_method='tiling', a positive stride make partition slices to not overlap and not touch, while a negative stride make partition slices to overlap by stride amount. If stride=0, the partition slices are contiguous (no spacing between partitions). When partitioning_method='sliding', only a positive stride (>= 1) is allowed. If int, the value is applied to all label array dimensions. If list or tuple, the length must match the number of dimensions of the array. If a dict, the dictionary must have has keys the label array dimensions.

  • kernel_size (int, tuple or dict, optional) – The shape of the desired partitions. Only positive values (>1) are allowed. The value -1 can be used to specify the full array dimension shape. If int, the value is applied to all label array dimensions. If list or tuple, the length must match the number of dimensions of the array. If a dict, the dictionary must have has keys the label array dimensions.

  • buffer (int, tuple or dict, optional) – The default is 0. Value by which to enlarge a partition on each side. The final partition size should be kernel_size + buffer. If partitioning_method='tiling' and stride=0, a positive buffer value corresponds to the amount of overlap between each partition. Depending on min_start and max_stop values, buffering might cause border partitions to not have same sizes. If int, the value is applied to all label array dimensions. If list or tuple, the length must match the number of dimensions of the array. If a dict, the dictionary must have has keys the label array dimensions.

  • include_last (bool, optional) – Whether to include the last partition if it does not match the kernel_size. The default is True.

  • ensure_slice_size (bool, optional) – Used only if include_last is True. If False, the last partition will not have the specified kernel_size. If True, the last partition is enlarged to the specified kernel_size by tentatively expanding it on both sides (accounting for min_start and max_stop).

Yields:

(xarray.Dataset or xarray.DataArray) – A xarray object patch.

ximage.patch.labels_patch.get_patches_isel_dict_from_labels(xr_obj, label_name, patch_size, variable=None, n_patches=None, n_labels=None, labels_id=None, centered_on='max', padding=0, n_patches_per_label=None, n_patches_per_partition=1, partitioning_method=None, n_partitions_per_label=None, kernel_size=None, buffer=0, stride=None, include_last=True, ensure_slice_size=True, debug=False, verbose=False)[source][source]#

Returnisel-dictionaries to extract patches around labels.

The isel-dictionaries are grouped by label_id and returned in a dictionary.

Please refer to ximage.patch.get_patches_from_labels for a detailed description of the function arguments.

Returns:

A dictionary of the form: {label_id: list_isel_dicts}.

Return type:

dict

ximage.patch.plot2d module#

Utility functions to display the patch extraction process around labels.

ximage.patch.plot2d.plot_label_patch_extraction_areas(xr_obj, label_name, patches_isel_dicts, partitions_isel_dicts, **kwargs)[source][source]#

Plot for debugging label patch extraction.

ximage.patch.slices module#

Slices utility functions.

ximage.patch.slices.enlarge_slice(slc, min_size, min_start=0, max_stop=inf)[source][source]#

Enlarge a slice object to have at least a size of min_size.

The function enforces the left and right bounds of the slice by max_stop and min_start. If the original slice size is larger than min_size, the original slice will be returned.

Parameters:

  • slc (slice) – The original slice object to be enlarged.

  • min_size (int) – The desired minimum size of the new slice.

  • min_start (int, optional) – The minimum value for the start of the new slice. The default is 0.

  • max_stop (int, optional) – The maximum value for the stop of the new slice. The default is np.inf.

Returns:

The new slice object with a size of at least min_size and respecting the left and right bounds. If the original slice object is already larger than min_size, the original slice is returned.

Return type:

slice

ximage.patch.slices.enlarge_slices(list_slices, min_size, valid_shape)[source][source]#

Enlarge a list of slice object to have at least a size of min_size.

The function enforces the left and right bounds of the slice to be between 0 and valid_shape. If the original slice size is larger than min_size, the original slice will be returned.

Parameters:

  • list_slices (list) – List of slice objects.

  • min_size ((int or tuple)) – Minimum size of the output slice.

  • valid_shape ((int or tuple)) – The shape of the array which the slices should be valid on.

Returns:

list_slices – The list of slices after enlarging it (if necessary).

Return type:

list

ximage.patch.slices.get_idx_bounds_from_slice(slc)[source][source]#

Get start and end indices of the slice.

Note: For index based selection, use idx_start:idx_end+1 !

ximage.patch.slices.get_nd_partitions_list_slices(list_slices, arr_shape, method, kernel_size, stride, buffer, include_last, ensure_slice_size)[source][source]#

Return the n-dimensional partitions list of slices of a initial list of slices.

ximage.patch.slices.get_partitions_slices(start, stop, slice_size, method, stride=None, buffer=0, include_last=True, ensure_slice_size=False, min_start=None, max_stop=None)[source][source]#

Create 1D partitioning list of slices.

Parameters:

  • start (int) – Slice start.

  • stop (int) – slice stop.

  • slice_size (int) – Slice size.

  • method (str) – Whether to retrieve 'tiling' or 'sliding' slices. If 'tiling', start slices are separated by stride + slice_size If 'sliding', start slices are separated by stride.

  • stride (int, optional) – Step size between slices. When 'tiling', the default is 0 When 'sliding', the default is 1. When 'tiling', a positive stride make slices to not overlap and not touch, while a negative stride make slices to overlap by stride amount. If stride is 0, the slices are contiguous (touch). When 'sliding', only a positive stride (>= 1) is allowed.

  • buffer – The default is 0. Value by which to enlarge a slice on each side. If stride=0 and buffer is positive, it corresponds to the amount of overlap between each tile. The final slice size should be slice_size + buffer. Depending on min_start and max_stop values, buffering might cause border slices to not have same sizes.

  • include_last (bool, optional) – Whether to include the last slice if not match slice_size. The default is True.

  • ensure_slice_size (False, optional) – Used only if include_last is True. If False, the last slice does not have size slice_size. If True, the last slice is enlarged to have slice_size, by tentatively expanded the slice on both sides (accounting for min_start and max_stop).

  • min_start (int, optional) – The minimum value that the slices start value can have (after i.e. buffering). If None (the default), assumed to be equal to start.

  • max_stop (int, optional) – Maximum value that the slices stop value can have (after i.e. buffering). If None (the default), assumed to be equal to stop.

Returns:

slices – List of slices.

Return type:

list

ximage.patch.slices.get_slice_around_index(index, size, min_start=0, max_stop=inf)[source][source]#

Get a slice object of size size around the index value.

If size is larger than max_stop-min_start, raise an error.

Parameters:

  • index (int) – The index value around which to retrieve the slice.

  • size (int) – The desired size of the slice around the index.

  • min_start (int, optional) – The default is np.inf. The minimum value for the start of the new slice. The default is 0.

  • max_stop (int) – The maximum value for the stop of the new slice.

Returns:

A slice object with the desired size and respecting the left and right bounds.

Return type:

slice

ximage.patch.slices.get_slice_from_idx_bounds(idx_start, idx_end)[source][source]#

Return the slice required to include the idx bounds.

ximage.patch.slices.get_slice_size(slc)[source][source]#

Get size of the slice.

Note: The actual slice size must not be representative of the true slice if slice.stop is larger than the length of object to be sliced.

ximage.patch.slices.pad_slice(slc, padding, min_start=0, max_stop=inf)[source][source]#

Increase/decrease the slice with the padding argument.

Does not ensure that all output slices have same size.

Parameters:

  • slc (slice) – Slice objects.

  • padding (int) – Padding to be applied to the slice.

  • min_start (int, optional) – The minimum value for the start of the new slice. The default is 0.

  • max_stop (int) – The maximum value for the stop of the new slice. The default is np.inf.

Returns:

list_slices – The list of slices after applying padding.

Return type:

list

ximage.patch.slices.pad_slices(list_slices, padding, valid_shape)[source][source]#

Increase/decrease the list of slices with the padding argument.

Parameters:

  • list_slices (list) – List of slice objects.

  • padding ((int or tuple)) – Padding to be applied on each slice.

  • valid_shape ((int or tuple)) – The shape of the array which the slices should be valid on.

Returns:

list_slices – The list of slices after applying padding.

Return type:

list

Module contents#

Patch Extraction module.