CodeCarvings Piczard V1.2 Help
Automatic Image Crop
See Also Send Feedback
Piczard Fundamentals - Core > Built-in Filters > Crop An Image > Automatic Image Crop

Glossary Item Box

CONTENTS

  1. Crop constraints
    1. Fixed size crop constraint
    2. Fixed aspect ratio crop constraint
    3. Free size crop constraint
  2. Crop margins
  3. Image selection strategy

 

 

1. Crop constraints

Please see the Example A.212 - "Crop an image / Automatic".

Piczard allows to "automatically" crop an image by using one of the three filters that inherit from CropConstraint:

  1. FixedCropConstraint class
    For more information please refer to: Fixed Size Crop Constraint.
  2. FixedAspectRatioCropConstraint class
    For more information please refer to: Fixed Aspect Ratio Crop Constraint.
  3. FreeCropConstraint class
    For more information please refer to: Free Size Crop Constraint.

 

All these classes allow to bind the output image size, independently from the source image size.

The CropConstraint class (that allows the "automatic" crop of images) is closely connected with the ImageCrop class (that allows the "manual" crop of images).

For more information please refer to: Manual Image Crop.

The CropConstraint class is also used by the PictureTrimmer WebControl in order to configure the crop constraints.

Please see:

When an image is processed, the CropConstrain class automatically calculate a new ImageSelection object
ImageSelection is a filter that contains 2 "sub" filters:

  1. An ImageTransformation filter that allow to resize the image before the crop process.
  2. An ImageCrop filter to crop the resized image.

Please see:

Margins and DefaultImageSelectionStrategy are two properties of the CropConstraint class that allows to control the behavior of a CropConstraint during the calculation of the ImageSelection.

For example, depending on the settings of the properties Margins and DefaultImageSelectionStrategy, the source image can be resized to contain the cropping area or not.

Figure 1: Image Resized and then Cropped (ImageSelectionStrategy = Slice).

 

 

1.a. Fixed size crop constraint

This crop constraint generates always fixed size images.

Copy Code
FixedCropConstraint pixelCropConstraint = new FixedCropConstraint(300, 200);
FixedCropConstraint inchCropConstraint =
new FixedCropConstraint(GfxUnit.Inch, 2.5F, 1.5F);
...

 

 

1.b. Fixed aspect ratio crop constraint

This crop constraint allows to generate fixed aspect ratio images.
Aspect ratio is the proportion of width to height, for example 16:9 = aspect ratio 1.777.
A square image has an aspect ratio of 1 (1:1) because the width and height are equal.

The FixedAspectRatioCropConstraint class allows to (optionally) define the minimum and/or the maximum size of the cropping area.
Since the width:height aspect ratio is fixed, only one dimension can be selected (either width or height) for the minimum and maximum size limit (the other dimension is automatically calculated by using a simple mathematical function).
For example, if the aspect ratio is 1 (square image) and the minimum image width is set to 100, obviously the minimum image height must be 100 (and vice-versa).

If both Min and Max are not null, then be sure that Max value is greater or equal to Min value otherwise an Exception is raised during the Image Processing phase.

Copy Code
FixedAspectRatioCropConstraint cropConstraint = new FixedAspectRatioCropConstraint(16F / 9F);
cropConstraint.LimitedDimension = SizeDimension.Height;
cropConstraint.Unit = GfxUnit.Inch;
cropConstraint.Min = 1.5F;    
// Min: 1 Inch
cropConstraint.Max = null;    // Max: No limit
...

 

 

1.c. Free size crop constraint

This crop constraint allows to generate images with free aspect ratio and custom width / height limits.

If both MinWidth and MaxWidth are not null, then be sure that MaxWidth value is greater or equal to MinWidth value otherwise an Exception is raised during the Image Processing phase.

If both MinHeight and MaxHeight are not null, then be sure that MaxHeight value is greater or equal to MinHeight value otherwise an Exception is raised during the Image Processing phase.

If you want to obtain an image with a fixed width and a variable height, then you can use the same value for the MinWidth and MaxWidth properties (and set MinHeight - MaxHeight to null).

Obviously the same technique can be used to get an image with a fixed height and a variable width.

Copy Code
FreeCropConstraint fixedWidthConstraint = new FreeCropConstraint();
fixedWidthConstraint.MinWidth = 200;     
// Fixed width: 200px
fixedWidthConstraint.MaxWidth = 200;     // Fixed width: 200px
fixedWidthConstraint.MinHeight = null;   // Variable height
fixedWidthConstraint.MaxHeight = null;   // Variable height
...

 

 

2. Crop margins

The Margins property allows to specify if (and how much) the cropped area can be external to the source image.

The CropMargins class allows to specify different values for the Horizontal margins (left and right) and for the Vertical margins (top and bottom).
Please note that if you, for example set the horizontal margin to 5 pixels, this mean that the total size of the horizontal margins is 10 pixels (5 pixels for the left margin a 5 pixels for the right margin).

Moreover the value of the margins must be expressed in the same unit of measure of the CropConstraint (please see CropConstraint.Unit property).

Crop Margins expressed in Inch Copy Code
CropConstraint cropConstraint = new FixedAspectRatioCropConstraint(150F / 80F);
cropConstraint.Unit = GfxUnit.Inch;
cropConstraint.Margins.Horizontal = 2F;   
// 2 Inch
cropConstraint.Margins.Vertical = 1.5F;   // 1.5 Inch
...

  

The Crop Margins are also used by PictureTrimmer in order to control the margins of cropping area.

 

 

3. Image selection strategy

The DefaultImageSelectionStrategy property of the CropConstraint class allows to control the way the ImageSelection is calculated.
The possible values are:

  1. CropConstraintImageSelectionStrategy.Slice (default value)
    This option allows to automatically Resize the image - and - to calculate a Crop Rectangle that stays fully inside the image.

    "Slice" Strategy Copy Code
    CropConstraint cropConstraint = new FixedCropConstraint(94, 50);
    cropConstraint.DefaultImageSelectionStrategy = CropConstraintImageSelectionStrategy.Slice;
    ...
  2. CropConstraintImageSelectionStrategy.WholeImage 
    This option allows to automatically Resize the image - and - to calculate a Crop Rectangle that contains the entire resized image (if possible).
    This strategy requires that the Margins are set.

    "WholeImage" Strategy Copy Code
    CropConstraint cropConstraint = new FixedCropConstraint(94, 50);
    cropConstraint.DefaultImageSelectionStrategy = CropConstraintImageSelectionStrategy.WholeImage;
    ...
  3. CropConstraintImageSelectionStrategy.DoNotResize 
    This option disable the resize of the image (if possible).

    "DoNotResize" Strategy Copy Code
    CropConstraint cropConstraint = new FixedCropConstraint(94, 50);
    cropConstraint.DefaultImageSelectionStrategy = CropConstraintImageSelectionStrategy.DoNotResize;
    ...

 

See Also

Piczard Fundamentals - Core
Manual Image Crop

©2013 Sergio Turolla. All Rights Reserved.