Getting started
---------------

``scikit-shape`` is a Python package for geometric image analysis.
It has image enhancement and segmentation functionality to aid
extract geometric structures, such as boundaries, regions, from images.
It also includes functions for quantitative shape analysis and statistics.
The basic geometric representations are polygonal curves, labeled images
and triangulated meshes. Users can import ``scikit-shape`` by: ::

    >>> import skshape

``scikit-shape`` builds on the Python packages
`NumPy <https://numpy.org>`_ and `SciPy <https://scipy.org>`_.
Most of the internal data are stored in NumPy arrays, and some of
the numerical computations rely on SciPy functionality.
Additional Python packages that are recommended to support and enhance
``scikit-shape`` functionality are `matplotlib <https://matplotlib.org>`_
for visualization, `scikit-image <https://scikit-image.org>`_ for image
processing, and `scikit-learn <https://scikit-learn.org>`_ for statistical
learning.

The geometric data structures in :mod:`skshape.geometry` submodule,
such as :class:`skshape.geometry.curve.Curve`, :class:`skshape.geometry.domain.Domain2d`,
are central to geometry processing: ::

    >>> from skshape.geometry.curve import Curve
    >>> from numpy import array
    >>> square = Curve( array([[0.2, 0.6, 0.6, 0.2], [0.2, 0.2, 0.6, 0.6]]) )

Supporting functions for numerical computations can be found in the submodule
:mod:`skshape.numerics`. For example, the user can define an image
interpolant with :class:`skshape.numerics.function.ImageFunction`,
and integrate it along the square curve. Functions for finite element
discretizations can be also be found in :mod:`skshape.numerics.fem`.

User can find image restoration and enhancement functions in the submodule
:mod:`skshape.image.enhancement`. For example, the function
:func:`skshape.image.enhancement.weighted_smoothing` can be used to remove
noise or variation in image while preserving edges. ::

    >>> from matplotlib.pyplot import imread
    >>> from skshape.image.enhancement import weighted_smoothing
    >>> image = imread('data/bacteria.jpg') / 255.0
    >>> smoothed_image = weighted_smoothing( image )

The submodule :mod:`skshape.image.segmentation` includes several algorithms
for image segmentation, i.e to detect objects, regions, boundaries in
images. The segmentation algorithms include iterative curve evolution
(likes snakes or active contours), iterative region labeling algorithms
by topology optimization or phase field evolution, and clustering.