Jpeg DNA commands usage
=======================

In order to use the commands from the terminal, you first need to install the package:

.. code-block:: bash

    python setup.py install

## Encoding

Use:

.. code-block:: bash

    jpdnae $IMG_FILE_PATH $DNA_OUT_FILE_PATH.pkl $alpha

or

.. code-block:: bash

    jpdnae.exe $IMG_FILE_PATH $DNA_OUT_FILE_PATH.pkl $alpha

## Decoding

Use:

.. code-block:: bash

    jpdnad $DNA_IN_FILE_PATH.pkl $IMG_OUT_FILE_PATH

or

.. code-block:: bash

    jpdnad.exe $DNA_IN_FILE_PATH.pkl$IMG_OUT_FILE_PATH


Jpeg DNA script usage
=====================

.. note::

    This implementation for the moment only deals with encoding and formatting the payload for the image data.
    It does not support the formatting of the variables necessary for decoding (frequency values of the DCT and size of the image).
    What can be recommended for the moment is to use a common general frequency table for the DCT values.

Some scripts have been implemented to use the Jpeg DNA codec. Specifically one for encoding and one for decoding. The scripts can be executed in the following day:

For gray_level
--------------

For encoding
~~~~~~~~~~~~

.. note::

    To simplify the commands, when no formatting is used, we have decided to use files with preconfigured names (available in jpegdna/scrips/config.ini)
    to save the categories, run/categories frequencies and image dimensions. The data from these files will be used for decoding.
    In the case where formatting is used, there is no need for thoses files, all the data being included in the format.


If you are using the image data to compute the frequencies of the DCT coefficients, you can run the encoding with:

.. code-block:: bash

    python -m jpegdna.scripts.jpegdna_encode $IMG_PATH $DNA_OUT_PATH $ALPHA

If you want to use the default frequencies for the DCT coefficient, you can add the '-d' option:


.. code-block:: bash

    python -m jpegdna.scripts.jpegdna_encode $IMG_PATH $DNA_OUT_PATH $ALPHA -d

If you want to enable the formatting system, you can add the '-f' option (also works in combination with the '-d' option):


.. code-block:: bash

    python -m jpegdna.scripts.jpegdna_encode $IMG_PATH $DNA_OUT_PATH $ALPHA -f
    python -m jpegdna.scripts.jpegdna_encode $IMG_PATH $DNA_OUT_PATH $ALPHA -d -f

.. important::

    The alpha value is a float parameter. When using formatting, we have to store this value inside the format.
    Since we want to optimize data usage, precision and robusteness to noise, we had to compromise on the precision available for the alpha value.
    In our program it is rounded to the nearest thousandth. This means that during decoding, an alpha value of for example 0.0025 will be interpreted as 0.003 .


For decoding
~~~~~~~~~~~~

If you are using non formatted data, to decode the image, you will still need to specify the alpha value (the frequencies and the image dimensions are transmitted through files that are specified in jpegdna/scripts/config.ini):

.. code-block:: bash

    python -m jpegdna.scripts.jpegdna_decode $DNA_IN_PATH $IMG_OUT_PATH no_format $ALPHA

If you want to use the default frequencies for the DCT coefficient, you can add the '-d' option before the no_format option:


.. code-block:: bash

    python -m jpegdna.scripts.jpegdna_decode $DNA_IN_PATH $IMG_OUT_PATH -d no_format $ALPHA

Otherwise, if the data is formatted, there is no need to specify the alpha value or if the frequencies are the preconfigured one because all the information necessary for decoding is already available in the format:


.. code-block:: bash

    python -m jpegdna.scripts.jpegdna_decode $DNA_IN_PATH $IMG_OUT_PATH

Evaluation script
~~~~~~~~~~~~~~~~~

An evaluation script is available under scripts/jpegdna_eval.py . The image to be tested can be specified at the beginning of the \_\_name\_\_ handler.
The script will run encoding and decoding for different dynamic (alpha) values and get the compression rate and PSNR for the whole process.
The dynamic values can be modified by the user in jpegdna_eval.py. An exception is for the moment used to check if the dynamic is not to small.

It can be executed from the root folder with:

.. code-block:: bash

    python -m jpegdna.scripts.jpegdna_eval


For RGB
-------

For encoding
~~~~~~~~~~~~

.. note::

    To simplify the commands, when no formatting is used, we have decided to use files with preconfigured names (available in jpegdna/scrips/config.ini)
    to save the categories, run/categories frequencies and image dimensions. The data from these files will be used for decoding.
    In the case where formatting is used, there is no need for thoses files, all the data being included in the format.


If you are using the image data to compute the frequencies of the DCT coefficients, you can run the encoding with:

.. code-block:: bash

    python -m jpegdna.scripts.jpegdnargb_encode $IMG_PATH $DNA_OUT_PATH $ALPHA

If you want to use the default frequencies for the DCT coefficient, you can add the '-d' option:


.. code-block:: bash

    python -m jpegdna.scripts.jpegdnargb_encode $IMG_PATH $DNA_OUT_PATH $ALPHA -d

If you want to enable the formatting system, you can add the '-f' option (also works in combination with the '-d' option):


.. code-block:: bash

    python -m jpegdna.scripts.jpegdnargb_encode $IMG_PATH $DNA_OUT_PATH $ALPHA -f
    python -m jpegdna.scripts.jpegdnargb_encode $IMG_PATH $DNA_OUT_PATH $ALPHA -d -f

.. important::

    The alpha value is a float parameter. When using formatting, we have to store this value inside the format.
    Since we want to optimize data usage, precision and robusteness to noise, we had to compromise on the precision available for the alpha value.
    In our program it is rounded to the nearest thousandth. This means that during decoding, an alpha value of for example 0.0025 will be interpreted as 0.003 .


For decoding
~~~~~~~~~~~~

If you are using non formatted data, to decode the image, you will still need to specify the alpha value (the frequencies and the image dimensions are transmitted through files that are specified in jpegdna/scripts/config.ini):

.. code-block:: bash

    python -m jpegdna.scripts.jpegdnargb_decode $DNA_IN_PATH $IMG_OUT_PATH no_format $ALPHA

If you want to use the default frequencies for the DCT coefficient, you can add the '-d' option before the no_format option:


.. code-block:: bash

    python -m jpegdna.scripts.jpegdnargb_decode $DNA_IN_PATH $IMG_OUT_PATH -d no_format $ALPHA

Otherwise, if the data is formatted, there is no need to specify the alpha value or if the frequencies are the preconfigured one because all the information necessary for decoding is already available in the format:


.. code-block:: bash

    python -m jpegdna.scripts.jpegdnargb_decode $DNA_IN_PATH $IMG_OUT_PATH

Evaluation script
~~~~~~~~~~~~~~~~~

An evaluation script is available under scripts/jpegdnargb_eval.py . The image to be tested can be specified at the beginning of the \_\_name\_\_ handler.
The script will run encoding and decoding for different dynamic (alpha) values and get the compression rate and PSNR for the whole process.
The dynamic values can be modified by the user in jpegdna_eval.py. An exception is for the moment used to check if the dynamic is not to small.

It can be executed from the root folder with:

.. code-block:: bash

    python -m jpegdna.scripts.jpegdnargb_eval

Verbosity
---------

A verbosity parameter can be adjusted for both encoding and decoding. This parameter is present in the jpegdna/scripts/config.ini file under the [VERB] section.
If the parameter enabled is set to False, the script wont print anything, if it is set to True, the level parameter will adjust the amount of information accessible:

.. list-table:: Verbosity levels

    *   - Level
        - Effects
    *   - 0
        - Input image, output strand printed during encoding, input strand, output image printed during decoding
    *   - 1
        - Basic info for encoding and decoding at the block level
    *   - 2
        - Basic info for quantization, zigzag, and DCT results on blocks
    *   - 3
        - Basic info for encoding and decoding at the value level
    *   - 4
        - Additional info for the HuffmanCoder class, helpful for debugging
    *   - 5
        - Additional info for the ValueCoder, helpful for debugging

The evaluation script is configurable directly in the script, where the codec is instanciated :python:`JPEGDNA(alpha, verbose=True, verbosity=0)` or :python:`JPEGDNARGB(alpha, verbose=True, verbosity=0)`.