ximage package

Subpackages

• ximage.accessor package
  • Submodules
  • ximage.accessor.methods module
    • XImage_Base_Accessor
      • XImage_Base_Accessor.label()
      • XImage_Base_Accessor.label_patches()
      • XImage_Base_Accessor.label_patches_isel_dicts()
    • XImage_DataArray_Accessor
      • XImage_DataArray_Accessor.plot_labels()
    • XImage_Dataset_Accessor
  • Module contents
    • XImage_DataArray_Accessor
      • XImage_DataArray_Accessor.plot_labels()
    • XImage_Dataset_Accessor
• ximage.labels package
  • Submodules
  • ximage.labels.labels module
    • check_core_dims()
    • get_data_array()
    • get_label_indices()
    • highlight_label()
    • label()
    • redefine_label_array()
  • ximage.labels.plot_labels module
    • get_label_colorbar_settings()
    • plot_labels()
  • Module contents
• ximage.patch package
  • Submodules
  • ximage.patch.checks module
    • check_buffer()
    • check_kernel_size()
    • check_padding()
    • check_partitioning_method()
    • check_patch_size()
    • check_stride()
  • ximage.patch.labels_patch module
    • find_point()
    • get_patches_from_labels()
    • get_patches_isel_dict_from_labels()
  • ximage.patch.plot2d module
    • plot_label_patch_extraction_areas()
  • ximage.patch.slices module
    • enlarge_slice()
    • enlarge_slices()
    • get_idx_bounds_from_slice()
    • get_nd_partitions_list_slices()
    • get_partitions_slices()
    • get_slice_around_index()
    • get_slice_from_idx_bounds()
    • get_slice_size()
    • pad_slice()
    • pad_slices()
  • Module contents

Module contents

ximage software.

ximage.label(xr_obj, *, variable=None, core_dims=None, min_value_threshold=-inf, max_value_threshold=inf, min_area_threshold=1, max_area_threshold=inf, footprint=None, sort_by='area', sort_decreasing=True, labeled_comprehension_kwargs=None, label_name='label')

Compute labels and and add as a coordinates to an xarray object.

Parameters:

• xr_obj (xarray.DataArray or xarray.Dataset) – xarray object.

• variable (str, optional) – Dataset variable to exploit to derive the labels array. Must be specified only if the input object is an xarray.Dataset.

• core_dims (tuple of str, optional) – Names of the two dimensions along which the labeling is applied. If the xarray DataArray is two-dimensional and core_dims is not provided, the core dimensions are inferred automatically from DataArray.dims. If the xarray DataArray has more than two dimensions, core_dims must be specified explicitly. In this case, labeling is applied independently over all remaining (non-core) dimensions. Example: for a 3D DataArray with dimensions (x, y, time), use core_dims=("x", "y") to apply labeling to each timestep.

• min_value_threshold (float, optional) – The minimum value to define the interior of a label. The default is -np.inf.

• max_value_threshold (float, optional) – The maximum value to define the interior of a label. The default is np.inf.

• min_area_threshold (float, optional) – The minimum number of connected pixels to be defined as a label. The default is 1.

• max_area_threshold (float, optional) – The maximum number of connected pixels to be defined as a label. The default is np.inf.

• footprint (int, numpy.ndarray or None, optional) – This argument enables to dilate the mask derived after applying min_value_threshold and max_value_threshold. If footprint = 0 or None, no dilation occur. If footprint is a positive integer, it create a disk(footprint) If footprint is a 2D array, it must represent the neighborhood expressed as a 2-D array of 1’s and 0’s. The default is None (no dilation).

• sort_by (callable or str, optional) – A function or statistics to define the order of the labels. Valid string statistics are "area", "maximum", "minimum", "mean", "median", "sum", "standard_deviation", "variance". The default is "area".

• sort_decreasing (bool, optional) – If True, sort labels by decreasing sort_by value. The default is True.

• labeled_comprehension_kwargs (dict, optional) – Additional arguments to be passed to dask_image.ndmeasure.labeled_comprehension. if sort_by is a callable.

Returns:

xr_obj – xarray object with the new label coordinate. In the label coordinate, non-labels values are set to np.nan.

Return type:

(xarray.DataArray or xarray.Dataset)

ximage.label_patches(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)

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.