This statement is used modify artwork items. It can scale, change the format, square, set to greyscale and compress artwork items. The image data returned by this statement is always extracted from the image produced by the final transformation. For that reason the size of the image can be changed. The image manipulations are performed in the order presented.
- Resolution Change
- No Resolution Change: An image's resolution will be preserved.
- You can choose a resolution of 72, 144, 200 or 300 PPI.
- Scale if condition is greater than
- You can scale an image if its x-y dimensions are greater than a selected value. You can choose to scale an image if either dimension is greater than the specified value (w | h). Alternately you can require that both the width and height must be greater than the supplied value (w&h) Note that Yate will not scale images smaller than 32x32. If you want to use the Settings-Artwork value, specify 0 or leave the field empty. Note that depending on subsequent manipulations, this may not reflect the final image size.
- Format Change
- No Format Change: An image's format, JPEG, PNG, etc. will be preserved.
- Force to JPEG: If an image is not a JPEG it will be converted to one.
- Force to PNG: If an image is not a PNG it will be converted to one.
- Compression
- Only available when the Format Change setting is not Force to PNG. When the Format Change setting is No Format Change, this option is ignored if the artwork item is not a JPEG.
The compression factor is specified as a number in the range of 0.0 to 1.0. A value of 0 implies use the system default compression value, which seems to be .75. The smaller the number, the smaller the image (more compression). The larger the number the larger the image (less compression). Note that there is no way to determine an image's current compression factor and because of that a specified compression is always applied.
- Square by fill mode
- If an artwork item does not have the same width and height the following will occur:
- The image's width and height will be resized to the larger of its initial width and height.
- The image will be centered in the expanded dimension.
- If the initial format is not JPEG or PNG the format will be changed to the value set in Settings-Artwork-Dragged image format.
The expanded area will be filled as follows:- by transparent fill: The fill colour will be transparency. Note that if the image is being saved as a JPEG, the filled area will more than likely become white during the transformation.
- by white fill: The fill colour will be white.
- by black fill: The fill colour will be black.
- runtime: Named variable Manipulate Artwork Fill Colour contains the fill colour in one of the following representations:
- empty
- White
- -
- Use clear (transparent) colour
- #rrggbb
- rr, gg and bb are each two hexadecimal digits representing the red, green and blue values.
- rgb(r,g,b)
- r, g and b must be decimal integers in the range of 0 through 255 and represent the associated colour component.
- rgba(r,g,b, a)
- r, g and b must be decimal integers in the range of 0 through 255 and represent the associated colour component. a is the alpha value between 0 and 1 where 0 is fully transparant and 1 is opaque. Note that alpha values only work as expected on png images. The semi transparent colour may be modified if a jpeg image is exported.
Any parsing errors will result in the fill colour being white.
- by stretching: The image will be stretched to fill the added area.
If you are squaring artwork the following special condition exists:
- if the fill mode is not by stretching.
- and a scale factor was set which was larger than the image's size.
- and the Force to scale option was specified.
- then the image size will be increased to the scale size with the squared image centered in the larger canvas. This guarantees an image of the requested scale size.
- Greyscale
- Forces the artwork image to be shades of grey.
- Pad - Round
- When enabled you can pad the image with a specified colour and round corners. When padding, you can specify to round the inner and/or padded portion of the image. The following named variables control the manipulations:
- Manipulate Artwork Pad
- When set to a non zero integer value, it represents the width of the pad in pixels to be applied.
- Manipulate Artwork Fill Colour
- Described above. This is the fill colour for the applied pad.
- Manipulate Artwork Round Percentage
- An integer value in the range of 0 through 50. 0 means no rounding. Other values describe the corner radius as a percentage. 50 implies oval or round.
- Manipulate Artwork Round Where
- Describes where rounding is to be applied. The named variable is only processed if the round percentage is non 0. The following holds:
- If no pad is being applied, this named variable is ignored. The original image is rounded.
- If a pad is being applied and this variable is empty, 0 or 1, the original image is rounded.
- If a pad is being applied and this variable is 2, the padding is rounded.
- If a pad is being applied and this variable is 3, both original image and padding is rounded.
Note that in order to round the outside edge of an image, transparency is applied. In these cases you should force the image to PNG. If not, the saved image will always have a solid colour applied.
- JPEG encoding
- Only available when the Format Change setting is not Force to PNG. When the Format Change setting is No Format Change, this option is ignored if the artwork item is not a JPEG.
- Any: The JPEG encoding is not explicitly changed. Note that when converting from an image format which is not JPEG, this will result in a baseline encoding.
- Baseline: If the image was a JPEG, its encoding will be changed to baseline if it is progressive. When converting from an image format which is not JPEG, this will force a baseline encoding.
- Progressive: If the image was a JPEG, its encoding will be changed to progress if it is baseline. When converting from an image format which is not JPEG, this will force a progressive encoding.
- Compress artwork if size is greater than
- This test is always performed last. If after all other transformations an artwork item's size in bytes is greater than the supplied value an attempt will be made to decrease the size. The size may be entered as #, #kb or as #mb. # can be a positive integer or decimal value. You can also enter 0 which implies the initial image's size. Successive compression attempts are made to get the size less than the desired value. Note that if an attempt to lower the size is necessary, an artwork item which at the time of the test is not a JPEG will be re-encoded as a baseline JPEG image ... regardless of the previous transformations!
FLAC files have a maximum image size of ~16MB. In order to make it easier to specify a value which meets the requirements of FLAC file encoding, the value may be entered as FLAC.
There is no guarantee that the resultant size will be less than the specified value. The success or failure of the functionality can only be determined by inspecting the size of the image after the statement execution completes.
The above manipulations are the primary functions. At least one must be set.
The selected functions can be applied to all artwork items, only the first artwork item or all but the first artwork item.
Additionally you can limit the functions to an artwork item at a particular index, to images with or without a specific picture type and/or the result of a comparison test on the description field. The index and description fields may contain any of the escape sequences described in Escape Sequences. Description tests are always performed case insensitive.
If you pass \sa for the index, it will match a single selected artwork item. More information can be found in the Accessing Selected Artwork topic.
While this action statement can be used while executing grouped, it is far more efficient when executed stepwise.
