[Images] Constrain
The [Images] Constrain module provides you with a flexible means to size images to a consistent state. It constrains the image to the specified settings with the goal of not distorting the image due to mismatches in the aspect ratio in the source image and desired target image.
The parameters that the module uses are detailed in the following table.
| Parameter | I/O | Description |
|---|---|---|
| FileSource | In | This parameter specifies the source of the image files as a FileList type of parameter. As a FileList, this can be specified as just the path for a specific folder. Or it can be specified as the path to a folder with a filename pattern to limit it to specific types of filenames or extensions. Or it can be linked to a preceding [Files] Find module for more flexibility in choosing what files to process. |
| TargetFolder | In | By default, re-encoded images are written to the target folder without affecting the original source image. This means the target folder must be a unique location from the source folder. |
| DeleteSourceFiles | In | The default value for this parameter is false (unchecked) meaning the original source image is not affected by the re-encoding process. If changed to true (checked), then the source image is deleted only once the modified file is successfully written to the target folder. |
| Operation | In | Crop (default): Determines the best way to obtain a usable image from the source image by cropping it to fit the target size while maintaining the targeted aspect ratio. Scale: Maximizes the original image inside the target size, maintaining the aspect ratio. If the source image and the target size are not an exact match to the aspect ratio, then the canvas color will be visible as either horizontal or vertical bars as needed. |
| Width | In | Either the target height or width of the output image should be specified. If only one is specified, then the aspect ratio of the target must be specified. If both are specified, then the target aspect ratio does not need to be as supplying both the width and height define the new aspect ratio. |
| Height | In | Optional sometimes as explained in the description for the Width parameter above. |
| AspectRatio | In | If only a target width or height (but not both) are specified, then the target aspect ratio must also be specified. Aspect ratio is supplied as a string value such as "16:9" which is the standard aspect ratio for 1080p HDTV resolution. An aspect ratio of "4:3" would match the aspect ratio of the older SDTV resolution. |
| SourceAnchor | In | None, Top, TopLeft, TopRight, Bottom, BottomLeft, BottomRight, Left, RightWhen determining how to best fit the source image into the target image, the default is None, which centers the source image both vertically and horizontally either within or over the canvas for the target image. This behavior can be modified by having the source image optionally anchor itself to one or two sides of the target. An example might be if all the source images you are processing are photos of people's faces and the top of their head is generally near the top of the photo, then you might change the anchor to Top to make sure it does not crop out the subject's hair. |
| CanvasColor | In | On scale operations when the canvas of the target image may wind up being slightly larger than the source image which would result in an uncovered portion of the canvas. In such a condition, you may want to set the canvas color to match your usage. Colors can be specified in the HEX-RGB format such as "#808080", or any of the standardized names recognized by the .NET System.Drawing.Color namespace. |
| AutoRotateOnExif | In | True (default): The image will automatically be rotated to the correct orientation if there is embedded EXIF sensor data that would indicate the image is not stored oriented to the expected viewing angle. False: The EXIF data is ignored, and no rotation will occur regardless of any EXIF data embedded in the image. |
| LogOutputLevel | In | Minimal: Normal output to the log. Verbose: More detailed output is written to the log, suitable for debugging purposes. |
| FileList | Out | When the module completes any work successfully, this is a FileList of all the specific images that were re-encoded and written to the target folder. |
We will review how the crop and scale operations work again for clarity and an important method to visualize this, beyond some example images, is to realize that when the target image is being prepared, it is going to be set at an appropriate size based on your specifications. Before the module attempts to fit the original image with this, this target image is just a blank canvas. The crop operation is going to trim off as little of the source image as possible in order for it to completely cover the blank canvas. The scale operation works a little differently in that it makes sure it includes all of the source image and does the best job it can do to get it to just perfectly get it to fit inside the canvas.
The crop operation is the method you would want to use if you are certain that the content of your image is either usually centered, or closest to one edge or corner of the source images. This allows you to get the maximum amount of the original image into your target image and will completely cover the canvas of the target image. Using crop allows you to wind up with a target image that is consistent in size and does not have any bleed through of the canvas on the target image.
((add example constrained:crop images))
The scale operation is the method you would want to use if you are either uncertain that the content of your image is going to be mostly centered or in a predictable relative position of the source image. This preserves your entire source image at the expense of having the canvas of the target image visible on one or two edges of the target image.
((add example constrained:scale images))
For more examples on the constrain module and the differences between the crop and scale operations, you can review the article below for examples and demonstrations on how this works.