API changes for skimage2

Other lists and resources that touch and inform this document:

• Meta-issue: pending API changes for 1.0 #5439 (comment pulled into this doc on 2023-02-10)
• A pragmatic pathway towards skimage2 (discuss.scientific-python.org/t/530)
• Restructuring of API #2538
• skimage2 API (GitHub Project)
• Registration and warping (GitHub Project) proposes disigning our API for n-dimensional registration.
• Old HackMD version of this list
• Timeline & process from skimage2 coordination meeting on January 29, 2024

Proposed API changes, doable ahead of skimage2

These should be doeable with normal deprecations.

• Move skimage.future.graph to skimage.graph. #3105
  • Completed in #6674
• Change output to out in skimage.filters.gaussian for consistency with other skimage functions supporting output to a user-provided array. #5439 (comment)
  • Older use of an in_place kwarg was already deprecated some in places in 0.19.
  • Deprecate output and positional args in filters.gaussian #7225
• Consistently use num_workers / workers for any parameter related to the number of threads/processes #5439 (comment)
  • Use num_workers instead of alternate parameter names #7302, WIP waiting for SPEC
• Resolve API inconsistency between the parameter names min_size and area_threshold in remove_small_holes and remove_small_objects #4003
• Address nomenclature for perimeter, area, volume in regionprops for 2D and 3D cases #3812.
• Remove skimage.viewer module as napari is a more actively developed and more powerful third-party alternative. #5439 (comment)
• Unify API on seed keyword for random seeds / generator #5359
  • Unify API on seed keyword for random seeds / generator

Proposed API changes surrounding skimage2

These changes are difficult to do with deprecations.

Whole library

• Consistently use image rather than img, arr, data, etc for image inputs. #5439 (comment)
• Where function signatures still use im1, im2, finally replace them with either image0, image1 or reference_image, target_image. #4187
  • Deprecate function plot_matches in favor of plot_matched_features #7255
  • Standardize function signature of compare_images. #7322
• Consistently use label_image as the parameter name refering to label images. #5439 (comment)
• Consistently preserve the range of user-provided inputs #5439 (comment).
  • See also this argument in #3009 (comment) for not rescaling to [0, 1], #5281 (comment), and Remove preserve_range kwarg #6319
• Functions that take in x/y (transposed) coordinates should take axis-aligned (aka rc) coordinates instead. (dead discussion link?), #5439 (comment)
• Audit our modules to cluster functions based on purpose and "interchangeability". #5439 (comment)
  • "The "big picture" in this case is to be sklearn-like in that it will enable easier interoperability between skimage and libraries replicating or extending the skimage API."
• Unify boundary extension mode names used across the library. #5439 (comment)
  • Currently we have 21 functions that use boundary mode names compatible with scipy.ndimage while we have another set of 12 functions that use names compatible with numpy.pad. Filtering/morphology functions tend to use the scipy.ndimage names while those in restoration/transforms tend to use the NumPy ones. Out of these the subtle difference between reflect/mirror/symmetric can be quite confusing to users with reflect unfortunately being a valid name, but with different behavior in the two conventions!
  • The list of specific funtions following each convention is here: dead discussion link?
• Have skimage.draw functions use a center argument rather than row, col for 2D and row, col, plane for 3D.#2538 (comment)
• Remove legacy property names. We have some properties that have even been renamed twice, leaving a mess of legacy names that are still supported, but create confusion for users. #5439 (comment)
• For algorithms that expect binary images, conform the way scikit-image deals with this. Either, only accept binary images (maybe preferred) or convert implicitly to binary images everywhere. #7095 (comment)

skimage.feature

• skimage.feature.canny's mode argument should not default to constant, since that usually results in an edge on the boundary. #6874 (comment) #5439 (comment)
• Use Euclidean distance in skimage.feature.peak_local_max as new default for the p_norm parameter #6608

skimage.filters

• Make functions in skimage.filters.threshold behave consistently. #5439 (comment)
  • Many currently return a numeric threshold value, but some return a thresholded image instead. It is likely that most users want the actual thresholded image, so that should be the default?
• Potentially move thresholding functions to their own new submodule, e.g. skimage.binarize. #2538

skimage.future

skimage.io

• Remove skimage.io module? Still a question on whether to leave this in place as a thin wrapper around imageio or whether we remove it altogether and just ask users to rely on imageio directly. #5439 (comment)

skimage.morphology

• Stop mirroring the structuring element in skimage.morphology.binary_dilation so that the behavior is consistent with other morphology operators. #6695 (comment)
• Use consistent API and parameters for footprint generation. #5439 (comment)
  • These are currently a mess of size, width, height, m, n, radius, etc. #4536. I would argue that we really only need a n-dimensional rectangle implementation rather than separate square, rectangle, cube, etc. Likewise an n-dimensional sphere (or more generally an n-dimensinal ellipse) rather than ball and disk.I would argue that the shape is not quite right currently in disk/ball/ellipse generation functions and should be changed (needing adjustment by 0.5 pixels internally): (dead discussion link?)
• Maybe consolidate footprint generating functions in their public footprint namespace or even skimage.shapes module? #2538
• Update API and behavior of morphological filters as described in #7238.

skimage.segmentation

• In watershed function, compute local minima with ski.morphology.label(ski.morphology.local_minima(image)) #7117?

skimage.transform

• Make behavior of the shear parameter in skimage.transform.AffineTransform consistent with the other ones. passing in a single scalar value should affect horizontal and vertical shear. #6717 (comment)
• Switch API to numpy style rc-coordinates / plan for nd-support. #3148
• If rescaling behavior in skimage.transform.warp is not removed, consider rescaling cval as well. #7336

skimage.util

• Rename skimage.util.img_as_* functions to rescale_to_*. #1234