.. index:: 
  !DocumentImage Class

.. _id3_document_document_image_class:

===============================================================================
DocumentImage Class
===============================================================================

Namespace: :ref:`id3.Document<reference_document>`

.. toctree::
  :hidden:

  clone<clone>
  compare<compare>
  correctGamma<correct_gamma>
  crop<crop>
  data<data>
  downscale<downscale>
  downscaleTo<downscale_to>
  extractRoi<extract_roi>
  extractRoiWithColor<extract_roi_with_color>
  flip<flip>
  flipTo<flip_to>
  fromBuffer<from_buffer>
  fromFile<from_file>
  fromNumpy<from_numpy>
  fromRawBuffer<from_raw_buffer>
  fromYuvPlanes<from_yuv_planes>
  getPixels<get_pixels>
  height<height>
  pad<pad>
  pixelDepth<pixel_depth>
  pixelFormat<pixel_format>
  reallocate<reallocate>
  resize<resize>
  resizeTo<resize_to>
  rotate<rotate>
  rotateTo<rotate_to>
  set<set>
  stride<stride>
  toBuffer<to_buffer>
  toBufferObject<to_buffer_object>
  toFile<to_file>
  toNumpy<to_numpy>
  toRawBuffer<to_raw_buffer>
  transpose<transpose>
  width<width>


Definition
----------
.. line-block::
    Represents a document image.

.. tab-set::

    .. tab-item:: Python
      :sync: Python

      .. code:: Python

        class DocumentImage

    .. tab-item:: Dart
      :sync: Dart

      .. code:: Dart

        class DocumentImage implements Finalizable

    .. tab-item:: C#
      :sync: C#

      .. code:: C#

        public partial class DocumentImage

    .. tab-item:: Java
      :sync: Java

      .. code:: Java

        public class DocumentImage implements AutoCloseable, Serializable

    .. tab-item:: Swift
      :sync: Swift

      .. code:: Swift

        public class DocumentImage

    .. tab-item:: C
      :sync: C

      .. code:: C

        typedef struct id3DocumentImage *ID3_DOCUMENT_IMAGE;



Usage
-----

.. tab-set::

    .. tab-item:: Python
      :sync: Python

      .. code:: Python

        documentImageInstance = DocumentImage()
        # ...

      **Explicit destruction**

      .. code:: Python

        # ...
        del documentImageInstance

    .. tab-item:: Dart
      :sync: Dart

      .. code:: Dart

        final documentImageInstance = sdk.DocumentImage();
        // ...

      **Explicit destruction**

      .. code:: Dart

        // ...
        documentImageInstance.dispose()

    .. tab-item:: C#
      :sync: C#

      .. code:: C#

        using (var documentImageInstance = new DocumentImage())
        {
           // ...
        }

      **Explicit destruction**

      .. code:: C#

        var documentImageInstance = new DocumentImage()
        // ...
        documentImageInstance.Dispose()

    .. tab-item:: Java
      :sync: Java

      .. code:: Java

        try (DocumentImage documentImageInstance = new DocumentImage()) {
        // ...
        }

      **Explicit destruction**

      .. code:: Java

        DocumentImage documentImageInstance = new DocumentImage();
        // ...
        documentImageInstance.close();

    .. tab-item:: Swift
      :sync: Swift

      .. code:: Swift

        private var documentImageInstance: DocumentImage? = nil
        documentImageInstance = try DocumentImage()

    .. tab-item:: C
      :sync: C

      .. code:: C

        ID3_DOCUMENT_IMAGE hDocumentImage{};
        int err = id3DocumentImage_Initialize(&hDocumentImage);
        if (err == ID3_SUCCESS) {
            // ...
            id3DocumentImage_Dispose(&hDocumentImage);
        }


Properties
----------

.. list-table:: 
  :width: 100%
  :widths: 30 5 65
  :header-rows: 1

  * - Name
    - Type
    - Description
  * - :ref:`data<id3_document_document_image_data_class_member>`
    - byte[]
    - Raw data buffer of the image.
  * - :ref:`height<id3_document_document_image_height_class_member>`
    - int
    - Height in pixels.
  * - :ref:`pixelDepth<id3_document_document_image_pixel_depth_class_member>`
    - int
    - Pixel depth.
  * - :ref:`pixelFormat<id3_document_document_image_pixel_format_class_member>`
    - :ref:`PixelFormat<id3_document_pixel_format_enum>`
    - Pixel format.
  * - :ref:`stride<id3_document_document_image_stride_class_member>`
    - int
    - Stride in bytes.
  * - :ref:`width<id3_document_document_image_width_class_member>`
    - int
    - Width in pixels.

Static Methods
--------------

.. list-table:: 
  :width: 100%
  :widths: 30 70
  :header-rows: 1

  * - Name
    - Description
  * - :ref:`fromBuffer<id3_document_document_image_from_buffer_class_method>`
    - Creates an Image from the specified data buffer.
  * - :ref:`fromFile<id3_document_document_image_from_file_class_method>`
    - Creates an Image from the specified file.
  * - :ref:`fromNumpy<id3_document_document_image_from_numpy_class_method>`
    - Creates an Image from the specified data buffer. Supported pixel formats are grayscale formats, BGR and RGB 24bits, and BGRA. For integers format, input datatype must be UINT8.
  * - :ref:`fromRawBuffer<id3_document_document_image_from_raw_buffer_class_method>`
    - Creates an Image from the specified raw data buffer.
  * - :ref:`fromYuvPlanes<id3_document_document_image_from_yuv_planes_class_method>`
    - Creates an Image from the specified YUV planes.
  * - :ref:`set<id3_document_document_image_set_class_method>`
    - Sets the Image object fields.

Methods
-------

.. list-table:: 
  :width: 100%
  :widths: 30 70
  :header-rows: 1

  * - Name
    - Description
  * - :ref:`clone<id3_document_document_image_clone_class_method>`
    - Clones the DocumentImage object.
  * - :ref:`compare<id3_document_document_image_compare_class_method>`
    - Computes the difference with another image.
  * - :ref:`correctGamma<id3_document_document_image_correct_gamma_class_method>`
    - Applies a gamma correction to the image.
  * - :ref:`crop<id3_document_document_image_crop_class_method>`
    - Crop a rectangular region of interest in the image according to the given bounds.
  * - :ref:`downscale<id3_document_document_image_downscale_class_method>`
    - Downscales the image in-place so that its maximum dimension is equal to the given maximum size, while preserving the aspect ratio.
  * - :ref:`downscaleTo<id3_document_document_image_downscale_to_class_method>`
    - Downscales the image so that its maximum dimension equals the given maximum size, while preserving the aspect ratio.
  * - :ref:`extractRoi<id3_document_document_image_extract_roi_class_method>`
    - Extracts a region of interest in the image according to the given bounds.
  * - :ref:`extractRoiWithColor<id3_document_document_image_extract_roi_with_color_class_method>`
    - Extracts a region of interest in the image according to the given bounds.
  * - :ref:`flip<id3_document_document_image_flip_class_method>`
    - Flips the image in-place.
  * - :ref:`flipTo<id3_document_document_image_flip_to_class_method>`
    - Flips the image.
  * - :ref:`getPixels<id3_document_document_image_get_pixels_class_method>`
    - Gets a pointer to the image pixels.
  * - :ref:`pad<id3_document_document_image_pad_class_method>`
    - Add padding around the image
  * - :ref:`reallocate<id3_document_document_image_reallocate_class_method>`
    - Reallocates the internal memory of the Image from parameters.
  * - :ref:`resize<id3_document_document_image_resize_class_method>`
    - Resizes the image in-place to the required width and height.
  * - :ref:`resizeTo<id3_document_document_image_resize_to_class_method>`
    - Resizes the image to the specified width and height.
  * - :ref:`rotate<id3_document_document_image_rotate_class_method>`
    - Rotates the image in-place to the specified angle.
  * - :ref:`rotateTo<id3_document_document_image_rotate_to_class_method>`
    - Rotates the image to the specified angle.
  * - :ref:`toBuffer<id3_document_document_image_to_buffer_class_method>`
    - Exports the image to a buffer.
  * - :ref:`toBufferObject<id3_document_document_image_to_buffer_object_class_method>`
    - Copies the image to a buffer in the specified format.
  * - :ref:`toFile<id3_document_document_image_to_file_class_method>`
    - Saves the image to the specified file.
  * - :ref:`toNumpy<id3_document_document_image_to_numpy_class_method>`
    - Exports the image to a numpy array (Python only)
  * - :ref:`toRawBuffer<id3_document_document_image_to_raw_buffer_class_method>`
    - Copies image pixels in the specified format into a buffer.
  * - :ref:`transpose<id3_document_document_image_transpose_class_method>`
    - Transposes the image object.
