pic2vec 0.8.2

Featurize images using a decapitated, pre-trained deep learning network

[](https://travis-ci.org/datarobot/pic2vec) [](https://coveralls.io/github/datarobot/pic2vec?branch=master)

Pic2Vec
================

Featurize images using a small, contained pre-trained deep learning network


* Free software: BSD license


Features
--------

This is the prototype for image features engineering. Currently, only
Python 2.7 is supported.

``pic2vec`` is a python package that performs automated feature extraction
for image data. It supports training models via the
DataRobot modeling API, as well as feature engineering on new image data.

## Input Specification

### Data Format

``pic2vec`` works on image data represented as either:
1. A directory of image files.
2. As URL pointers contained in a CSV.
3. Or as a directory of images with a CSV containing pointers to the image files.

If no CSV is provided with the directory, it automatically generates a CSV to store the features with the appropriate images.

Each row of the CSV represents a different image, and image rows can also have columns containing other data about the images as well. Each image's featurized representation will be appended as a series of new columns at the end of the appropriate image row.


### Constraints Specification
The goal of this project was to make the featurizer as easy to use and hard to break as possible. If working properly, it should be resistant to badly-formatted data, such as missing rows or columns in the csv, image mismatches between a CSV and an image directory, and invalid image formats.

However, for the featurizer to function optimally, it prefers certain constraints:
* The CSV should have no missing columns or rows, and there should be full overlap between images in the CSV and the image directory

* If checking predictions on a separate test set (such as on Kaggle), the filesystem needs to sort filepaths consistently with the sorting of the test set labels. The order in the CSV (whether generated automatically or passed in) will be considered the canonical order for the feature vectors.

The featurizer can only process .png, .jpeg, or .bmp image files. Any other images will be left out of the featurization by being represented by zero vectors in the image batch.

## Quick Start

The following Python code shows a typical usage of `pic2vec`:

```python
import pandas as pd
from pic2vec import ImageFeaturizer

image_column_name = 'images'
my_csv = 'path/to/data.csv'
my_image_directory = 'path/to/image/directory/'

my_featurizer = ImageFeaturizer(depth=2)

my_featurizer.load_data(image_column_name, csv_path = my_csv, image_path = my_image_directory)

my_featurizer.featurize()
```

## Examples

To get started, see the following example:

1. [Cats vs. Dogs](examples/Cats_v_Dogs_Test_Example.ipynb): Dataset from combined directory + CSV

Examples coming soon:
1. [Facebook Like Prediction](examples/Facebook_Like_Predictor.ipynb): Dataset from unsupervised directory only, with PCA visualization
1. [URLs](examples/): Dataset from CSV with URLs and no image directory


## Installation

See the [Installation Guide](docs/guides/installation.md) for details.

### Installing Keras/Tensorflow
If you run into trouble installing Keras or Tensorflow as a dependency, read the [Keras installation guide](https://keras.io/#installation) and [Tensorflow installation guide](https://www.tensorflow.org/install/) for details about installing Keras/Tensorflow on your machine.


## Using Featurizer Output With DataRobot
``pic2vec`` generates a CSV that is ready to be dropped directly into the DataRobot application, if the data has been labelled with a variable that can be considered a target in the CSV. The image features are each treated like regular columns containing data.


### Running tests

To run the unit tests with ``pytest``, run

```
py.test tests
```



Credits
---------

This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [audreyr/cookiecutter-pypackage](https://github.com/audreyr/cookiecutter-pypackage) project template.


=======
History
=======
0.8.2 (2017-08-14)
------------------
* Updated trafaret requirement for PyPi package

0.8.1 (2017-08-07)
------------------
* Fixed bugs with robust naming
* Added error message for failed image conversion

0.8.0 (2017-08-02)
------------------
* Added robust naming options to the generated csv files

0.7.1 (2017-08-02)
------------------
* Fixed PIL truncated image bug

0.7.0 (2017-08-02)
------------------
* Fixed bug with CSV badly formed URLs
* Fixed mistake with InceptionV3 preprocessing happening for every model

0.6.3 (2017-07-25)
------------------
* Added Travis and Coveralls for testing and coverage automation
* Repo went public
* Python 3.x compatibility

0.6.2 (2017-07-14)
------------------
* Fixed image format recognition.

0.6.1 (2017-07-12)
------------------
* Directory-only now natural sorted.

0.6.0 (2017-07-11)
------------------
* Added multi-column support
* Added missing image column to csv

0.5.0 (2017-07-06)
------------------
* Renamed to pic2vec
* Tests parametrized

0.4.3 (2017-07-03)
------------------
* Second round of code review- optimized code, better type checking with trafaret

0.4.2 (2017-06-30)
------------------
* Improved README test examples

0.4.1 (2017-06-30)
------------------
* Fixed documentation

0.4.0 (2017-06-29)
------------------
* Added ability to call multiple models, and packaged in SqueezeNet with weights.

0.3.0 (2017-06-26)
------------------
* Created installation instructions and readme files, ready for prototype distribution

0.2.9(2017-06-25)
------------------
* Fixed import problem that prevented generated csvs from saving

0.2.8(2017-06-25)
------------------
* Fixed variable name bugs

0.2.7(2017-06-25)
------------------
* Changed image_directory_path to the more manageable image_path
* Made testing module and preprocessing module slightly more robust.

0.2.6(2017-06-23)
------------------
* Added features-only csv test, and got rid of the column headers in the file
* Added Documentation to data featurization modeules

0.2.5(2017-06-23)
------------------
* 100% test coverage
* Fixed a problem where a combined directory + csv was appending to the wrong
rows when there was a mismatch between the directory and the csv.

0.2.4(2017-06-22)
------------------
* Fixed more bugs in build_featurizer

0.2.3(2017-06-22)
------------------
* Fixed build_featurizer troubles with building new csv paths in current directory

0.2.2(2017-06-22)
------------------
* Full requirements for keras imported

0.2.1 (2017-06-22)
------------------
* Bug fixes

0.2.0 (2017-06-22)
------------------
* Second release on PyPI.
* Install keras with tensorflow backend specifically

0.1.0 (2017-06-14)
------------------
* First release on PyPI.