.. index:: 
  !DocumentImage.downscaleTo Method
  
.. _id3_document_document_image_downscale_to_class_method:

===============================================================================
DocumentImage.downscaleTo Method
===============================================================================

Module: :ref:`DocumentImage<id3_document_document_image_class>`

Definition
----------

Downscales the image so that its maximum dimension equals the given maximum size, while preserving the aspect ratio.

.. note:: If the maximum dimension is already smaller than the given maximum size, the function does nothing and the returned scale ratio is 1.


.. tab-set::

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

      .. code:: Python

        downscale_to(self, dst_document_image: DocumentImage, max_size: int) -> float

      **Parameters**

        .. line-block::

          ``dst_document_image`` :ref:`DocumentImage<id3_document_document_image_class>`
          :guilabel:`in` Destination image.

          ``max_size`` int
          :guilabel:`in` Maximum image size, in pixels. The value must be greater than 0.


      **Returns**

        .. line-block::

          ``float``
          The scaling ratio applied to the image. Range is ]0:1].

      **Exceptions**

        .. line-block::

          :ref:`DocumentException<id3_document_document_exception>`
          An error has occurred during Document Library execution.


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

      .. code:: Dart

        double downscaleTo(DocumentImage dstDocumentImage, int maxSize)

      **Parameters**

        .. line-block::

          ``dstDocumentImage`` :ref:`DocumentImage<id3_document_document_image_class>`
          :guilabel:`in` Destination image.

          ``maxSize`` int
          :guilabel:`in` Maximum image size, in pixels. The value must be greater than 0.


      **Returns**

        .. line-block::

          ``double``
          The scaling ratio applied to the image. Range is ]0:1].

      **Exceptions**

        .. line-block::

          :ref:`DocumentException<id3_document_document_exception>`
          An error has occurred during Document Library execution.


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

      .. code:: C#

        public float DownscaleTo(DocumentImage dstDocumentImage, int maxSize)

      **Parameters**

        .. line-block::

          ``dstDocumentImage`` :ref:`DocumentImage<id3_document_document_image_class>`
          :guilabel:`in` Destination image.

          ``maxSize`` int
          :guilabel:`in` Maximum image size, in pixels. The value must be greater than 0.


      **Returns**

        .. line-block::

          ``float``
          The scaling ratio applied to the image. Range is ]0:1].

      **Exceptions**

        .. line-block::

          :ref:`DocumentException<id3_document_document_exception>`
          An error has occurred during Document Library execution.


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

      .. code:: Java

        public float downscaleTo(DocumentImage dstDocumentImage, int maxSize) throws DocumentException

      **Parameters**

        .. line-block::

          ``dstDocumentImage`` :ref:`DocumentImage<id3_document_document_image_class>`
          :guilabel:`in` Destination image.

          ``maxSize`` int
          :guilabel:`in` Maximum image size, in pixels. The value must be greater than 0.


      **Returns**

        .. line-block::

          ``float``
          The scaling ratio applied to the image. Range is ]0:1].

      **Exceptions**

        .. line-block::

          :ref:`DocumentException<id3_document_document_exception>`
          An error has occurred during Document Library execution.


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

      .. code:: Swift

        public func downscaleTo(dstDocumentImage: DocumentImage, maxSize: Int32) throws -> Float

      **Parameters**

        .. line-block::

          ``dstDocumentImage`` :ref:`DocumentImage<id3_document_document_image_class>`
          :guilabel:`in` Destination image.

          ``maxSize`` Int32
          :guilabel:`in` Maximum image size, in pixels. The value must be greater than 0.


      **Returns**

        .. line-block::

          ``Float``
          The scaling ratio applied to the image. Range is ]0:1].

      **Exceptions**

        .. line-block::

          :ref:`DocumentException<id3_document_document_exception>`
          An error has occurred during Document Library execution.


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

      .. code:: C

        int id3DocumentImage_DownscaleTo (
            ID3_DOCUMENT_IMAGE hDocumentImage, 
            ID3_DOCUMENT_IMAGE hDstDocumentImage, 
            int maxSize, 
            float * scaleRatio)

      **Parameters**

        .. line-block::

          ``hDocumentImage`` :ref:`ID3_DOCUMENT_IMAGE<id3_document_document_image_class>`
          :guilabel:`in` Handle to the DocumentImage object.

          ``hDstDocumentImage`` :ref:`ID3_DOCUMENT_IMAGE<id3_document_document_image_class>`
          :guilabel:`in` Destination image.

          ``maxSize`` int
          :guilabel:`in` Maximum image size, in pixels. The value must be greater than 0.

          ``scaleRatio`` float *
          :guilabel:`out` The scaling ratio applied to the image. Range is ]0:1].


      **Returns**

        .. line-block::

          ``int``
          An error code.
          See :ref:`id3DocumentError<id3_document_document_error_enum>` file for the list of possible error codes.


