===========================
CroppingImageField Examples
===========================


Archetype's ImageField resizes Images so they fit into a rectangle defined by it's sizes.

::

  ImageField(
          name='normalImage',
          sizes= {'article' : (313, 198),},
          widget=ImageWidget(
              label="Ordinary ImageField",
              description="Image will be resized",
              )
          )


You can use CroppingImageField to define a long- and short-edge size of an image.
The field will find out whether the image is in portrait or landscape format and
resize it accordingly.

::

  CroppingImageField(
          name='croppedImage',
          long_edge_size=508,
          short_edge_size=323,
          sizes={'article' : (313, 198),},
          widget=CroppingImageField._properties['widget'](
              label="Cropped Image",
              description="Image will be cropped to a ratio of 508x323",
              )
          )


If you upload a landscape image in 4:3 format for these two fields you'll get the following result:


* `normalImage` will leave some unused space on the left and right side
  since the original image is to narrow for the wanted size.

* `croppedImage` will give you an image that fits the wanted size by cropping off some
  pixels of the top and the bottom of the orginal image.

.. image:: img/result-landscape.jpg


For an portrait image in 4:3 you'll get the following result:

* `normalImage` will neither do cropping nor change the aspect ratio of the image.
  it just leave some more unused space on the left and right side.

* `croppedImage` will recognize a portrait image, crops some pixels on the left and right side
  of the image to make it fit the long-edge to short-edge ratio.

  The image will be 313 pixels high and 198 pixels wide (although size usually
  limits to a height of 198 pixels). You can use force_format (see `Forcing an image format`_)
  to make the portrait image fit the size exactly.

.. image:: img/result-portrait.jpg


Forcing an image format
=======================

In some usecases, the result for the portrait 4:3 image with `croppedImage` field
might be not satisfying since by specifying ``sizes= {'article' : (313, 198),},``
in an ImageField you usually except an image that is
max. 313 pixels wide and 198 pixels high.

CroppingImageField also supports this usecase thanks to the `force_format` property.

You can force an image to be in `portrait` or in `landscape` format.

::

  CroppingImageField(
          name = 'forcedFormatImage',
          long_edge_size = 508,
          short_edge_size = 323,
          force_format = 'landscape'
          sizes = {'article' : (313, 198),},
          widget = CroppingImageField._properties['widget'](
              label = "Image with forced format",
              description = "Image will be cropped to a landscape image with ratio of 508x323",
              )
          )


This way, the result for the landscape image will be the same as for `croppedImage` above,
but the portrait image will be cropped to landscape format and the result will fit
the 313x198 pixels:


.. image:: img/result-landscape-force-format.jpg

.. image:: img/result-portrait-force-format.jpg