.. _image-export-image-label:

Export image
~~~~~~~~~~~~

The *Export image* step saves the converted ``BitmapImage`` with additional metadata information into a standard file format.

After the *Convert* pipeline (see :ref:`image-convert-pipeline-label`) produced a ``BitmapImage`` data, one might want to store the result on the file system as part of a delivery, or to further process the image with another application. This step is meant for this use case.

The current version supports the following output formats:

* Joint Photographic Experts Group (JPEG) format
* JPEG 2000 (JP2) format
* Tag Image File Format (TIFF) with GeoTIFF extension
* PGM Image File Format (PGM) - a textual greyscale image format

Exporting into Joint Photographic Experts Group (JPEG) format
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To export into JPEG format one must obtain both the original ``RawImage`` and the produced ``BitmapImage`` along with the ``JpegConfig`` configuring the output file.

.. code-tabs::
    .. code-tab:: cpp
        :title: C++

        P1::ImageSdk::RawImage rawImage;
        P1::ImageSdk::BitmapImage bitmap;
        P1::ImageSdk::JpegConfig config;
        std::string filename;

        config.compression = 80;

        P1::ImageSdk::JpegWriter jpegWriter(filename, bitmap, rawImage, config);

    .. code-tab:: csharp
        :title: C#

        P1.ImageSdk.RawImage rawImage;
        P1.ImageSdk.BitmapImage bitmap;
        P1.ImageSdk.JpegConfig config;
        System.String filename;

        config.compression = 80;

        rawImage.WriteAsJpeg(filename, bitmap, config);


Exporting into JPEG 2000 (JP2) format
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To export into JP2 format one must obtain both the original ``RawImage`` and the produced ``BitmapImage`` along with the ``Jp2Config`` configuring the output file.

.. code-tabs::
    .. code-tab:: cpp
        :title: C++

        P1::ImageSdk::RawImage rawImage;
        P1::ImageSdk::BitmapImage bitmap;
        P1::ImageSdk::Jp2Config config;
        std::string filename;

        P1::ImageSdk::Jp2Writer jp2Writer(filename, bitmap, rawImage, config);

    .. code-tab:: csharp
        :title: C#

        P1.ImageSdk.RawImage rawImage;
        P1.ImageSdk.BitmapImage bitmap;
        P1.ImageSdk.Jp2Config config;
        System.String filename;

        rawImage.WriteAsJp2(filename, bitmap, config);


Exporting into Tag Image File Format (TIFF)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To export into TIFF format one must obtain both the original ``RawImage`` and the produced ``BitmapImage`` along with the ``TiffConfig`` configuring the output file.

.. code-tabs::
    .. code-tab:: cpp
        :title: C++

        P1::ImageSdk::RawImage rawImage;
        P1::ImageSdk::BitmapImage bitmap;
        P1::ImageSdk::TiffConfig config;
        std::string filename;

        config.tileSize = P1::ImageSdk::tileSize512;

        P1::ImageSdk::TiffWriter tiffWriter(filename, bitmap, rawImage, config);

    .. code-tab:: csharp
        :title: C#

        P1.ImageSdk.RawImage rawImage;
        P1.ImageSdk.BitmapImage bitmap;
        P1.ImageSdk.TiffConfig config;
        System.String filename;

        config.tileSize = P1.ImageSdk.TiffTileSize.tileSize512;

        rawImage.WriteAsTiff(filename, bitmap, config);

Exporting into PGM Format (PGM)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To export into PGM format one must obtain both the original ``RawImage`` and the produced ``BitmapImage``
The PGM image format is a textual greyscale format. The greyscale values are found by taking the luminosity value of 
the Red, Green and Blue channel.

.. code-tabs::
    .. code-tab:: cpp
        :title: C++

        P1::ImageSdk::RawImage image;
        P1::ImageSdk::BitmapImage bitmap;
        std::string filename;

        P1::ImageSdk::PgmWriter(filename, bitmap, image);
        
    .. code-tab:: csharp
        :title: C#

        P1.ImageSdk.RawImage rawImage;
        P1.ImageSdk.BitmapImage bitmap;
        P1.ImageSdk.Jp2Config config;
        System.String filename;

        rawImage.WriteAsPgm(filename, bitmap);


Output color space
^^^^^^^^^^^^^^^^^^

By default the ImageSDK will output images in sRGB color space (IEC 61966-2-1). Although this color space has relatively small gamut, it is adequate for most applications. 
In case the end user needs to output the images in wider color gamut, ImageSDK can produce them in Adobe RGB (1998) color space (IEC 61966-2-5:2007).

.. code-tabs::
    .. include-tab:: ../../labels/cppConvertColorSpace
        :language: cpp
        :title: C++

    .. include-tab:: ../../labels/csConvertColorSpace
        :language: csharp
        :title: C#

The such converted bitmap needs to be supplemented with an Adobe RGB (1998) color profile so that the writer can output a file which is interpreted correctly by any color managed viewer.

.. code-tabs::
    .. include-tab:: ../../labels/cppExportColorSpace
        :language: cpp
        :title: C++

    .. include-tab:: ../../labels/csExportColorSpace
        :language: csharp
        :title: C#




Adding GeoTIFF fields to the metadata
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To output a valid GeoTIFF file, the ImageSdk requires a couple of fields to be defined in the TiffConfig structure.
A minimum set of required parameters are currently supported.

* GTRasterTypeGeoKey
* GTModelTypeGeoKey
* ModelTiepointTag
* ModelPixelScaleTag
* ModelTransformationTag
* GTCitationGeoKey

See an example of how to add the fields to the configuration.

.. code-tabs::
    .. include-tab:: ../../labels/cppSetGeoTiff
        :language: cpp
        :title: C++

    .. include-tab:: ../../labels/csSetGeoTiff
        :language: csharp
        :title: C#