wai.tfimageclass 0.0.15
Image classification using tensorflow.
License: Apache 2.0 License

Image classification (not object detection) using `tensorflow <https://www.tensorflow.org/>`__.

Based on example code located here:

`https://www.tensorflow.org/hub/tutorials/image_retraining <https://www.tensorflow.org/hub/tutorials/image_retraining>`__


Installation
============

- install virtual environment::

    virtualenv -p /usr/bin/python3.7 venv

- install tensorflow (1.x or 2.x works)

  - with GPU (1.x)::

      ./venv/bin/pip install "tensorflow-gpu<2.0.0"

  - with GPU (2.x)::

      ./venv/bin/pip install "tensorflow-gpu>=2.0.0"

  - CPU only (1.x)::

      ./venv/bin/pip install "tensorflow<2.0.0"

  - CPU only (2.x)::

      ./venv/bin/pip install "tensorflow>=2.0.0"

- install library

  - via pip::

      ./venv/bin/pip install wai.tfimageclass

  - from source (from within the directory containing the `setup.py` script)::

      ./venv/bin/pip install .


Usage
=====

All scripts support `--help` option to list all available options.


Train
-----

- For training, use module `wai.tfimageclass.train.retrain` or console script `tfic-retrain`
- For evaluating a built model, use module `wai.tfimageclass.train.stats` or console script `tfic-stats`


Training data
-------------

All the data for building the model must be located in a single directory, with each sub-directory representing
a *label*. For instance for building a model for distinguishing flowers (daisy, dandelion, roses, sunflowers, tulip),
the data directory looks like this::

   |
   +- flowers
      |
      +- daisy
      |
      +- dandelion
      |
      +- roses
      |
      +- sunflowers
      |
      +- tulip


Predict
-------

Once you have built a model, you can use it as follows:

- For making predictions for a single image, use module `wai.tfimageclass.predict.label_image` or console
  script `tfic-labelimage`
- For polling images in a directory and making continuous predictions with CSV companion files, use
  module `wai.tfimageclass.predict.poll` or console script `tfic-poll`
- For making predictions via Redis (https://redis.io/), i.e., broadcasting the image bytes on one
  channel and receiving the JSON predictions on another channel, use `wai.tfimageclass.predict.label_redis`
  or console script `tfic-label-redis`

Changelog
=========

0.0.15 (2022-05-10)
-------------------

- added `wai/tfimageclass/predict/label_redis.py` module (console script: `tfic-label-redis`) that
  allows making predictions via Redis backend (image bytes in, JSON predictions out).


0.0.14 (2021-04-20)
-------------------

- added `--replace_chars` option to `retrain.py` to better manage what characters get replaced with blanks in labels


0.0.13 (2021-04-16)
-------------------

- added ability to `stats.py` to output confusion matrix as well (`--output_conf_matrix` and `--conf_matrix_type`)


0.0.12 (2021-04-14)
-------------------

- `poll.py` now handles keyboard interrupts properly
- `stats.py` can use tflite model now as well, using `--graph_type tflite`


0.0.11 (2021-01-26)
-------------------

- `poll.py` can output predictions now in: csv, xml, json
- `label_image.py` can output predictions to stdout or a file and in: plaintext (current), csv, xml, json


0.0.10 (2021-01-25)
-------------------

- removed ability to split images into grid from `poll.py`
- added `tfic-export` tool to export saved model folder to Tensorflow lite model
- added support for using tflite models to `tfic-poll` and `tfic-labelimage`


0.0.9 (2020-10-21)
------------------

- `poll.py` accidentally redefined variable for resetting the session.


0.0.8 (2020-10-21)
------------------

- `poll.py` now re-initializes the Tensorflow session every X processed images to avoid
  out of memory problems (`--reset_session` option).


0.0.7 (2020-09-22)
------------------

- `poll.py` now outputs the top-X predictions with the correct labels/probability


0.0.6 (2020-09-02)
------------------

- `poll.py` in non-continuous mode now works as expected (didn't scan input directory previously)


0.0.5 (2020-08-06)
------------------

- `label_image.py`, `poll.py` and `stats.py` can now re-use the info JSON file
  generated by `retrain.py` to simplify command-line parameters (input_height,
  input_width, input_layer, output_layer, labels)
- improved help output of argument parsers: outputting description, command-line
  and default values now


0.0.4 (2020-08-04)
------------------

- `poll.py` now has new `--continuous` flag to allow for continuous or single batch predictions


0.0.3 (2020-07-28)
------------------

- `poll.py`: added ability to split images into grid of equal sized images, obtaining
  a classification for each sub-image.
- fixed license: now uses Apache 2.0 instead of MIT


0.0.2 (2019-11-14)
------------------

- added missing `MANIFEST.in`


0.0.1 (2019-11-01)
------------------

- initial release