.. highlight:: java


.. _label-working-with-images:

###################
Working With Images
###################


The Image API allows the user to generate an image representation of the fingerprint for a given term, text or expression, 
offering an interesting visual perspective on the Retina. In particular the ``compare`` method of the Image API allows 
the user to make qualitative judgements with respect to the fingerprints.


All information regarding the methods of the ``ImageAPI`` can be found under the *Image* tab in our |swagger_api|.

.. |swagger_api| raw:: html

   <a href="http://api.cortical.io" target="_blank">interactive API documentation</a>
   
REST API
########

The image functions are all implemented as ``POST`` calls, where the input document is attached to an ``HTTP-Header``.
For example, using ``curl``, (all on one line) ::

   curl -k -X POST -H "api-key: yourApiKey" -H "Content-Type: application/json" 
      "http://api.cortical.io/rest/image?retina_name=en_associative&image_scalar=2
         &plot_shape=circle&image_encoding=base64%2Fpng&sparsity=1.0" -d @yourInputText.txt
   
Where ``yourInputText.txt`` would be a file containing the body of the call, e.g.::

   {
    "term": "jaguar"
   } 

producing the following image

.. figure:: _static/jaguar-sq-fp2.png
  :align: center


The API endpoints for the ``Image API`` are:

* ``image``
* ``image/compare``
* ``image/bulk``



API Clients
###########

The ``FullClient`` object available in the `Java <https://github.com/cortical-io/retina-api-java-sdk>`_, 
`Python <https://github.com/cortical-io/retina-sdk.py>`_, and
`JavaScript <https://github.com/cortical-io/RetinaSDK.js>`_ client libraries has the following methods for calling the ``image`` endpoints:

* ``getImage``
* ``compareImage``
* ``getImages``