.. _bulk-upload:

Console Bulk Photo Upload
======================================================

To bulk-upload photos to the dossier database, you can use the :program:`findface-security-uploader` utility from the FindFace Multi package (in addition to the web interface upload functionality). Use this utility when you need to upload a large number of photos (more than 10,000).

.. warning::
   In the current version, the :program:`findface-security-uploader` utility does not support cars and bodies, only faces.  

.. tip::
   To view the :program:`findface-security-uploader` help, execute:

   .. code::

      findface-security-uploader --help

Do the following:

#. Write the list of photos and metastrings to a CSV or TSV file. 

   .. important::
      The file used as a metadata source must have the following format: ``path to photo | metastring``. 

   To prepare a TSV file, use either a :download:`script <_scripts/tsv_builder.py>` or the ``find`` command.

   .. note::
      Both the script and the command in the examples below create the ``images.tsv`` file. Each image in the list will be associated with a metastring coinciding with the image file name in the format ``path to photo | metastring``.

   To build a TSV file listing photos from a specified directory (``/home/user/25_celeb/`` in the example below), run the following command:  

   .. code::

      python3 tsv_builder.py /home/user/25_celeb/

   The ``find`` usage example:

   .. code::

      find photos/ -type f -iname '*g' | while read x; do y="${x%.*}"; printf "%s\t%s\n" "$x" "${y##*/}"; done

#. Create a job file out of a CSV or TSV file by using ``add``. As a result, a file ``enroll-job.db`` will be created and saved in a current directory. 

   .. code::

      findface-security-uploader add images.tsv

   The ``add`` options:

   * ``--format``: input file format, ``tsv`` by default,
   * ``--delimiter``: field delimiter, by default ``"\t"`` for TSV, and ``","`` for CSV.

   .. note::
      A job file represents a sqlite database which can be opened on the :program:`sqlite3` console.
 
#. Process the job file by using ``run``.

   .. code::

      findface-security-uploader run --dossier-lists 2 --api http://127.0.0.1:80 --user admin --password password

   The important ``run`` options:

   * ``--parallel``: the number of photo upload threads, 10 by default. The more threads you use, the faster the bulk upload is completed, however it requires more resources too.
   * ``--all-faces``: upload all faces from a photo if it features several faces.
   * ``--api``: ``findface-security`` API URL, ``http://127.0.0.1:80/`` by default. Mandatory option.
   * ``--user``: login. Mandatory option.
   * ``--password``: password. Mandatory option.
   * ``--dossier-lists``: comma-separated list of the watch lists id’s. Mandatory option.
   * ``--failed``: should an error occur during the job file processing, correct the mistake and try again with this option.
   * ``--inactive``: mark new dossiers as inactive.
   * ``--noface``: include images without detection.