# API changes for skimage2 [no longer updated]

**!!! This list is continued at https://github.com/scikit-image/scikit-image/wiki/API-changes-for-skimage2 !!!**

---

Other lists and resources that touch and inform this document:

- [Meta-issue: pending API changes for 1.0 #5439](https://github.com/scikit-image/scikit-image/issues/5439#issuecomment-1046269796) ([comment](https://github.com/scikit-image/scikit-image/issues/5439#issuecomment-1046269796) pulled into this doc on 2023-02-10)
- [A pragmatic pathway towards skimage2 (discuss.scientific-python.org/t/530)](https://discuss.scientific-python.org/t/a-pragmatic-pathway-towards-skimage2/530/10)
- [Restructuring of API #2538](https://github.com/scikit-image/scikit-image/issues/2538)
- [skimage2 API (GitHub Project)](https://github.com/scikit-image/scikit-image/projects/12)
- [Registration and warping (GitHub Project)](https://github.com/scikit-image/scikit-image/projects/8) proposes disigning our API for n-dimensional registration.

## Proposed API changes, doable ahead of skimage2

These should be doeable with normal deprecations.

- [x] Move `skimage.future.graph` to `skimage.graph`. [#3105](https://github.com/scikit-image/scikit-image/issues/3105)
- Completed in [#6674](https://github.com/scikit-image/scikit-image/pull/6674)
- [ ] Change `output` to `out` in `skimage.filters.gaussian` for consistency with other skimage functions supporting output to a user-provided array. [#5439 (comment)](https://github.com/scikit-image/scikit-image/issues/5439#issuecomment-1046269796)
- Older use of an in_place kwarg was already deprecated some places in 0.19).
- [ ] Consistently use `workers` for any parameter related to the number of threads/processes instead of `num_workers`, `num_threads`, etc. [#5439 (comment)](https://github.com/scikit-image/scikit-image/issues/5439#issuecomment-1046269796)
- [ ] Resolve API inconsistency between the parameter names `min_size` and `area_threshold` in `remove_small_holes` and `remove_small_objects` [#4003](https://github.com/scikit-image/scikit-image/issues/4003)

## 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)](https://github.com/scikit-image/scikit-image/issues/5439#issuecomment-1046269796)
- [ ] Where function signatures still use `im1, im2`, finally replace them with either `image0, image1` or `reference_image, target_image`. [#4187](https://github.com/scikit-image/scikit-image/pull/4187)
- [ ] Consistently use `label_image` as the parameter name refering to label images. [#5439 (comment)](https://github.com/scikit-image/scikit-image/issues/5439#issuecomment-1046269796)
- [ ] Consistently preserve the range of user-provided inputs [#5439 (comment)](https://github.com/scikit-image/scikit-image/issues/5439#issuecomment-1046269796).
- See also this argument in [#3009 (comment)](https://github.com/scikit-image/scikit-image/issues/3009#issuecomment-644533409) for not rescaling to [0, 1], [#5281 (comment)](https://github.com/scikit-image/scikit-image/pull/5281#issuecomment-864646679), and [Remove preserve_range kwarg #6319](https://github.com/scikit-image/scikit-image/pull/6319)
- [ ] Functions that take in x/y (transposed) coordinates should take axis-aligned (aka rc) coordinates instead. [(dead discussion link?)](https://github.com/scikit-image/scikit-image/discussions/5651#discussioncomment-1492411), [#5439 (comment)](https://github.com/scikit-image/scikit-image/issues/5439#issuecomment-1046269796)
- [ ] Audit our modules to cluster functions based on purpose and "interchangeability". [#5439 (comment)](https://github.com/scikit-image/scikit-image/issues/5439#issuecomment-1046269796)
- "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)](https://github.com/scikit-image/scikit-image/issues/5439#issuecomment-1046269796)
- 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?](https://github.com/scikit-image/scikit-image/discussions/5651#discussioncomment-1492429)
- [ ] Have `skimage.draw` functions use a `center` argument rather than row, col for 2D and row, col, plane for 3D.[#2538 (comment)](https://github.com/scikit-image/scikit-image/issues/2538#issuecomment-531203041)
- [ ] Unify API on seed keyword for random seeds / generator [#6258](https://github.com/scikit-image/scikit-image/pull/6258)
- [ ] 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)](https://github.com/scikit-image/scikit-image/issues/5439#issuecomment-1046269796)

### `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)](https://github.com/scikit-image/scikit-image/pull/6874#issuecomment-1500554308) [#5439 (comment)](https://github.com/scikit-image/scikit-image/issues/5439#issuecomment-1500549134)
- [ ] Use Euclidean distance in `skimage.feature.peak_local_max` as new default for the `p_norm` parameter [#6608](https://github.com/scikit-image/scikit-image/issues/6608)

### `skimage.filters`

- [ ] Make functions in `skimage.filters.threshold` behave consistently. [#5439 (comment)](https://github.com/scikit-image/scikit-image/issues/5439#issuecomment-1046269796)
- 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](https://github.com/scikit-image/scikit-image/issues/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)](https://github.com/scikit-image/scikit-image/issues/5439#issuecomment-1046269796)

### `skimage.morphology`

- [ ] Stop mirroring the structuring element in `skimage.morphology.binary_dilation` so that the behavior is consistent with other morphology operators. [#6695 (comment)](https://github.com/scikit-image/scikit-image/pull/6695#issuecomment-1413179791)
- [ ] Use consistent API and parameters for footprint generation. [#5439 (comment)](https://github.com/scikit-image/scikit-image/issues/5439#issuecomment-1046269796)
- These are currently a mess of size, width, height, m, n, radius, etc. [#4536](https://github.com/scikit-image/scikit-image/issues/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?)](https://github.com/scikit-image/scikit-image/discussions/5652)
- [ ] Maybe consolidate footprint generating functions in their public `footprint` namespace or even `skimage.shapes` module? [#2538](https://github.com/scikit-image/scikit-image/issues/2538)

### `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)](https://github.com/scikit-image/scikit-image/pull/6717#issuecomment-1423602071)
- [ ] Switch API to numpy style rc-coordinates / plan for nd-support. [#3148](https://github.com/scikit-image/scikit-image/pull/3148)

### `skimage.util`

- [ ] Rename `skimage.util.img_as_*` functions to `rescale_to_*`. [#1234](https://github.com/scikit-image/scikit-image/issues/1234)

### `skimage.viewer`

- [ ] Remove `skimage.viewer` module as napari is a more actively developed and more powerful third-party alternative. [#5439 (comment)](https://github.com/scikit-image/scikit-image/issues/5439#issuecomment-1046269796)