scikit-image/TASKS.txt

How to contribute to ``scikits.image``
======================================

Developing Open Source is great fun!  Join us on the `scikits-image mailing
list <http://groups.google.com/group/scikits-image>`_ and tell us which of the
following challenges you'd like to solve.

* Mentoring is available for those new to scientific programming in Python.
* The technical detail of the `development process`_ is given below.

.. contents::
   :local:

Tasks
-----

Adapt existing code for use
```````````````````````````
These snippets and packages have already been written.  Some need to be
modified to work as part of the scikit, others may be lacking in documentation
or tests.

   * Connected components
   * `Hough transform <http://mentat.za.net>`_
   * `Shortest paths <http://mentat.za.net>`_
   * `Grey-level co-occurrence matrices <http://mentat.za.net/hg>`_
   * Marching squares (investigate patent issues)
   * Nadav's bilateral filtering (first compare against CellProfile's code)
   * 2D iso-contour finding (sub-pixel precision) [ask Zach Pincus]
   * 2D image warping via thin-plate splines [ask Zach Pincus]

Merge code provided by `CellProfiler <http://www.cellprofiler.org>`_ team
`````````````````````````````````````````````````````````````````````````
* Canny filter (Canny, J., *A Computational Approach To Edge Detection*,
  IEEE Trans. Pattern Analysis and Machine Intelligence, 8:679-714, 1986)
* Prewitt filter - convolution with ``[[1,1,1], [0,0,0], [-1,-1,-1]]`` to
  detect edges
* Sobel filter - convolution with ``[[1,2,1], [0,0,0], [-1,-2,-1]]`` to
  detect edges
* Roberts filter - convolution with diagonal and anti-diagonal
  kernels to detect edges
* Bilateral filter
  (http://groups.csail.mit.edu/graphics/bilagrid/bilagrid_web.pdf)
  - edge detection using both spatial and intensity information
* Convex hulls of objects in a labels matrix
* Minimum enclosing circles of objects in a labels matrix
* Map-coloring of a labels matrix - assign each label a color so that
  all adjacent labels have different colors
* Skeletonize, spur removal, thinning, thickening, and other morphological
  operations on binary images, framework for creating arbitrary morphological
  operations using a 3x3 grid.
* Skeletonize objects in a labels matrix

Their SVN repository is read-accessible at

- https://svn.broadinstitute.org/CellProfiler/trunk/CellProfiler/pyCellProfiler/

The files for the above algorithms are

- https://svn.broadinstitute.org/CellProfiler/trunk/CellProfiler/pyCellProfiler/cellprofiler/cpmath/cpmorphology.py
- https://svn.broadinstitute.org/CellProfiler/trunk/CellProfiler/pyCellProfiler/cellprofiler/cpmath/filter.py

There are test suites for the files at

- https://svn.broadinstitute.org/CellProfiler/trunk/CellProfiler/pyCellProfiler/cellprofiler/cpmath/tests/test_cpmorphology.py
- https://svn.broadinstitute.org/CellProfiler/trunk/CellProfiler/pyCellProfiler/cellprofiler/cpmath/tests/test_filter.py

Quoting a message from Lee Kamentsky to Stefan van der Walt sent on
5 August 2009::

  We're part of the Broad Institute which is non-profit. We would be happy
  to include our algorithm code in SciPy under the BSD license since that is
  more appropriate for a library that might be integrated into a
  commercial product whereas CellProfiler needs the more stringent
  protection of GPL as an application.

Thanks to Lee Kamentsky, Thouis Jones and Anne Carpenter and their colleagues
who contributed.

Write new functionality
```````````````````````
* Plugin structure for image IO

Rework linear filters
`````````````````````
* Should take kernel or function for parameter (currently only takes function)
* Kernel shape should be specifiable (currently defaults to image shape)
* Due to the above, the tests run unnecessarily slowly

API generation for source distribution
``````````````````````````````````````
The source package is currently distributed without the auto-generated API doc
sources.  This means that users who download the source tar-file need to
install ``scikits.image`` before building docs.  We can skirt the issue by
checking in the API files into the repository (done) -- but the doc build
process needs to be updated to use these distributed files if they cannot be
generated from source.

Development process
-------------------
 * Go to `http://github.com/stefanv/scikits.image
   <http://github.com/stefanv/scikits.image>`_  and follow the instructions on
   making your own fork/branch.
 * Make changes to your branch, committing locally as you progress.
 * Push your changes back to github.
 * Ping stefan to request a merge into the main development branch.

.. note::

   Do *not* merge the main branch into yours.  You may rebase,
   as long as you are `aware of its dangers <http://tinyurl.com/lll385>`_
   (also see `LWN article <http://tinyurl.com/nqcbkj>`_).

All of this may be intimidating if you've never used git before, so we'd
happily accept plain old unified diffs (``git diff`` or ``diff -u a.txt
b.txt``) as well.

Guidelines:
```````````
 * All code should have tests.
 * All code should be documented, to the same
   `standard <http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines>`_
   as NumPy and SciPy.
 * Follow the `Python PEPs <http://www.python.org/dev/peps/pep-0008/>`_
   where possible.
 * All major changes should be `posted for review
   <http://codereview.appspot.com>`_ to the `mailing list
   <http://groups.google.com/group/scikits-image>`_.

Bugs
````
Please `report bugs on Github <http://github.com/stefanv/scikits.image>`_.