davisking/dlib — pull request #2 by patricksnape (2014-12-10 18:07:58+00:00)
Title: WIP: Python API Updates

As @davisking and I briefly discussed over email, I've been working on some updates to the Python API. This is currently a work in progress (WIP) but I wanted anyone to be able to take a look at what I've got so far.

# Current Additions
- Exposed ``test_simple_object_detector`` using existing images and bounding boxes. This is a very similar addition to being able to train with existing images and boxes.
- Exposed the ``dlib.point`` type denoting an ``(x, y)`` point.
- Exposed the ``full_object_detection``. This contains a ``dlib.rectangle`` and a vector of ``dlib.point``.
- Exposed a constructor to enable training
- Exposed the ``shape_predictor`` class
- Is callable: ``shape_predictor(numpy_image, dlib.rectangle) -> dlib.full_object_detection``
- Exposed a new ``shape_predictor_training_options`` in the same vein as the ``simple_object_detector_training_options``
- Exposed ``train_shape_predictor``
- From both XML and already loaded images and ``dlib.full_object_detection``s
- ``train_shape_predictor(dataset_filename, predictor_output_filename, options)``
- ``train_shape_predictor(images, full_object_detections, predictor_output_filename, options)``
- Exposed ``test_shape_predictor``
- From XML and already loaded images and ``dlib.full_object_detection``s. The scales parameter is the overload that allows normalisation of the error. This returns the mean average error as a double.
- ``test_shape_predictor(dataset_filename, predictor_filename)``
- ``test_shape_predictor(images, full_object_detections, predictor_filename)``
- ``test_shape_predictor(images, full_object_detections, scales, predictor_filename)``
- Very mild refactoring of some things so I could try and use them across the predictor and the detectors.

# Changes I would like to see
Here I just wanted to list a few things that I would like to change that would count as breaking/more radical changes to the current API

- Change the current training API so that it takes keyword arguments instead of the struct. This would feel a lot more Pythonic and is totally possible as long as the default arguments are not objects.
- Change the current training API so that saving is optional, and by default it actually just returns you the detector. This would be a lot better for cases whereby you might not want to waste time saving down and reloading back from disk. This is cleaner to implement if the output_path is a keyword argument and defaults to an empty string.

# Changes @davisking may want to see
Here I'm going to be so bold as to guess things that @davisking may want to see, but are not things that I personally need.

- Rendering of the fitted shapes using a window type viewer, similar to how detections are currently viewed.
- A Python example showing training and fitting of a shape predictor.