NIST Special Database 27A
==============================================

The tool described on this page can be used to upload the NIST SD-27A database into PiAnoS.

Background information
-----------------------------

The NIST SD-27A is a reference collection of marks and prints. From `the website <http://www.nist.gov/itl/iad/ig/sd27a.cfm>`_:

	NIST Special Database 27A - The National Institute of Standards and Technology in conjunction with the Federal Bureau of Investigation has maintained a database of grayscale fingerprint images, corresponding minutiae and selected latent fingerprints corresponding to fingerprint images in the data set. This data set is known as Special Database 27 (SD-27) and provides 500ppi imagery. In 2010, this data set was expanded to provide 1000ppi imagery to the research community and has been made available for electronic distribution. This data set is herein referred to as SD-27A.  
	
Downloads and information can be found at  `<http://www.nist.gov/itl/iad/ig/sd27a.cfm>`_.

The provided tool creates a folder in PiAnoS that contains all matching pairs (latent vs. corresponding reference print), each one as a separate exercise.

Note that the tool performs automatic conversions from JPEG 2000 to PNG, because PiAnoS does not natively handle JP2 images.


Prerequisites
-------------------------

	- The NIST SD-27A files
	
	- Python Imaging Library. Available as ``python-imaging`` on most Linux distros, and as installer from `the PIL website <http://www.pythonware.com/products/pil/>`_ on Windows.
	
	- PythonMagick. Available as ``python-pythonmagick`` on Linux, and as installer from the `Unofficial Windows Binaries for Python Extension Packages <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_ on Windows.
	
	- :doc:`pianos_py`
	
Downloads
-------------------------

`import_nist_sd27.py <https://ips-labs.unil.ch/pianos/downloads/tools/import_nist_sd27.py>`_


Usage
-------------------------

The script takes two mandatory arguments:

	- the path to the directory were SD-27A was unpacked. This directory should contain the file ``Readme.txt`` and the two directories: ``500ppi-Legacy`` and ``1000ppi``.
	
	- the "pgsql URL" to the database. It is a convenient way to specify all of database name, host, port, username, and password in a single argument, using the syntax "pgsql://username:password@host:port/dbname".
	
Since the dataset contains many marks and prints, there is a huge number of `mark-print` combinations that can be used as exercises in PiAnoS. ``import_nist_sd27.py`` has several modes to select how these marks and prints are combined. Note that not all marks have a corresponding print, that many marks have two corresponding prints, and many prints do not have a corresponding mark.

=============== ======================================================================
Mode            Description
=============== ======================================================================
1               **Default mode.** For each mark that has at least one corresponding 
                print, an exercise is created. Marks that have more than one print
                only appear once, with the first matching print.
2               Like mode 1, but additionnal exercises are created for all prints
                of a mark (thus, the same mark can appear multiple times). This is a
                superset of mode 1.
=============== ======================================================================

Additionnal parameters:

	- ``--mode``: see table above.
	- ``--dry-run``: to check how many exercises would be created - this does not modify the database in any way.
	- ``--folder``: to set the name of the PiAnoS folder
	
	
Examples
-------------------------

Getting extended usage information on Linux:

.. code:: bash

	$ python import_nist_sd27.py --help

On Linux, assuming SD27A has been upacked to ``/home/bob/sd27a``, and using a database named `pianos` on localhost, with username `uname` and password `pwd`, using the default mode:

.. code:: bash

	$ python import_nist_sd27.py /home/bob/sd27a pgsql://uname:pwd@localhost/pianos
	
On Windows, assuming SD27A has been unpacked to ``C:\Users\Bob\sd27a``, and using a database named `pianos` on the remote server `pianos-srv`, with username `pianos` and password `passwd`, using mode 2:

.. code:: bat

	import_nist_sd27.py -m 2 "C:\Users\Bob\sd27a" pgsql://pianos:passwd@pianos-srv/pianos
	
	
