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
   * Color-space manipulations (so far rgb2hsv was done by Nicolas Pinto,
                                needs documentation)
   * `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)
   * Cached ImageCollection from `supreme <http://mentat.za.net/supreme>`_
   * 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.

Documentation: API generation
`````````````````````````````
The API documentation is auto-generated from source.  Currently, it's
mostly functional but not very clean.  For example, we currently see things
like:

 - Module: ``io.collection``
   ...
 - Module: ``io.pil_imread``
   ...
 - Module: ``io.sift``

These should be combined into one.  All around, there are small things that
can be improved, such as the chaotic index table, the class attribute tables,
etc.

Write new functionality
```````````````````````
* Plugin structure for image IO
* Handle multi-page images (possibly as ImageCollection?)

Complete the build process
``````````````````````````
* Fix scripts for building Cython extensions (see `this thread
  <http://www.nabble.com/problem-with-numpy.distutils-and-Cython-td25100957.html#a25100957>`_).

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.
 * 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>`_.