menpo/menpo — pull request #400 by jabooth (2014-07-21 08:13:46+00:00)
Title: Features as functions

This PR removes `image.features` and instead makes the feature functions we already had robust to working with menpo images and numpy arrays. This is achieved through using one of three decorators as appropriate:
```python
@imgfeature
def feature_written_for_menpo_image(image):
# image will always be a Menpo Image
# must return a Menpo Image.

@ndfeature
def feature_writen_for_ndarray(pixels):
# pixels will always be a ndarray of pixels
# must return an ndarray of pixels

@winitfeature
def feature_that_uses_menpos_windowiterator(pixels):
# pixels will always be an ndarray.
# I have to return the feature ndarray and the centres
# from window iterator. This will be used for
# correcting masks and landmarks.
```
The decorators ensure that each of these feature functions can be used in a consistent manor - if you provide a `MaskedImage` with landmarks to any of these you will get a `MaskedImage` back with corrected mask and landmarks - if you provide simply a numpy array to any of these you will get just a numpy array back.

A nice consequence of this design is that any features we expose from Cyvlfeat can be instantly made usable in the fit framework by simply adding the `@ndfeature` decorator to them.

This part of the work is fairly small, but it has some large consequences for the fitmultilevel module. Currently there is a lot of machinery in fitmulitlevel that deals with checking and applying features. This is massively simplified in this PR, but it does mean a fairly large change set, so we will need to be vigilant for problems.

This PR is not yet ready, but I need to give something at GOSH my attention for a few days so I thought I would put it up so that people can start reviewing. I've listed what I think needs doing at the end of the PR, and will work through these in the next few days.

Hit me with any questions!

### TODO
- [ ] Unify feature checking between SDAAM, SDM, AAM
- [ ] Add wrapt to setup.py
- [ ] investigate fitting issues on AAM (constrain_landmarks_to_bounds?)
- [ ] Decide how to handle constrain_landmarks_to_bounds in fitmultilevel
- [ ] Unit tests for new feature decorators
- [ ] Fix Menpo notebooks
- [ ] Documentation of feature API (maybe in user guide?)