# 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.

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.

# 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: