(v13) HqnImage Options

Key

Type

Description

BestFit

Boolean

(Optional, default = false , new in Harlequin 13) If BestFit is true , then if the image size would fit the target page size better if rotated, the image will be rotated by 90° counter-clockwise.

Ignored if ImageScaling is /FromImage ,

/DeviceRelative or /UnitSquare .

DeviceMultiplier

Array of two positive numbers

(Optional, default = [ 1 1 ] , new in Harlequin 13) If ImageScaling is DeviceRelative then the image will be scaled such that each image pixel covers DeviceMultiplier pixels, using the first value for the X dimension and the second for the Y dimension of the image.

ErrorOnFail

Boolean

(Optional, default = false , new in Harlequin 13) The image processing calls in HqnImage will not normally trigger an error report if the file type does not match those requested, but doing so can sometimes be useful for debugging. Setting ErrorOnFail to true will trigger an error in such cases.

hqn_image_do_setpagedevice

Boolean

(Optional, deprecated from Harlequin 13) This option was used to control functionality that’s now set by SetPageSize and SetRenderResolution .

hqn_image_do_showpage

Boolean

(Optional, default = true , except when ImageScaling is /UnitSquare , in which case it is overridden to false ) If true then the page will be rendered after processing the image.

ImageScaling

Enumeration of names

(Optional, default = /FromImage , new in Harlequin 13) Defines how the image data is scaled for rendering. The value must be one of the names listed in Table: HqnImage ImageScaling values .

NoTiling

Boolean

(Optional, default = false , new in Harlequin 13) If true, then the tiling parameters set by settilingparams will be ignored, and the whole image will be rendered. Tiling of images is also disabled if hqn_image_do_setpagedevice is false, if hqn_image_do_showpage is false, or if ImageScaling is set to /UnitSquare.

ScaleToSize

Array of two positive numbers, or null

(Optional, default = null , new in Harlequin 13) If not null, this array will define the page size used when scaling an image to fit. The first value in the array indicates the width and the second the height, both in default user units. See ImageScaling for details.

SetPageSize

Boolean

(Optional, default = true , new in Harlequin 13) If true , the PageSize in the page device will be set to the results of the calculation from ImageScaling . If false , the PageSize will be left unchanged, but the image will still be scaled. Overridden to false when ImageScaling =

/UnitSquare .

SetRenderResolution

Boolean

(Optional, default = false , new in Harlequin 13) If true and if ImageScaling =

/FromImage , then the value of HWResolution in the page device will be set to the image resolution calculated from ImageScaling . If false , HWResolution will be left unchanged.

CAUTION: This behavior differs from Harlequin versions before 13.

SubImage

Integer

(Optional, no default) For image formats that support multiple images in a single file (such as TIFF), this is a zero-based index selecting the image to be analyzed or run.

XResolution , YResolution

Numbers

(Optional, default set from image file or by image type) These values may be used to override the output size of the image when ImageScaling = /FromImage .

/DeviceRelative

The page size is calculated from the number of pixels in the image, the value of HWResolution in the page device and the value of DeviceMultiplier .

/FillPageSize

The image is uniformly scaled to be as small as possible and still completely cover the area defined by ScaleToSize (if that is not null ) or the PageSize in the page device (if ScaleToSize is null ).

/FromImage

The page size is calculated from the number of pixels in the image, combined with the image resolution. If the image file does not set its own resolution, then the default resolution set in HqnImage for that file type will be used. And if XResolution and/or YResolution are set, those will be used to override the resolution from the image file or the defaults.

/ScaleToHeight

The image is uniformly scaled so that it is as tall as the second number in ScaleToSize (if that is not null ) or the PageSize in the page device (if ScaleToSize is null ). You can force this to scale the larger dimension of the image to that height by setting BestFit to true and the first element of ScaleToSize to a very small number. You can force the smaller dimension to the desired height by setting BestFit to true and the first element of ScaleToSize to a very large number.

/ScaleToPageSize

The image is uniformly scaled to be as large as possible and still fit within the area defined by ScaleToSize (if that is not null) or the PageSize in the page device (if ScaleToSize is null ).

/ScaleToWidth

The image is uniformly scaled so that it is as wide as the first number in ScaleToSize (if that is not null ) or the PageSize in the page device (if ScaleToSize is null ). You can force this to scale the larger dimension of the image to that width by setting BestFit to true and the second element of ScaleToSize to a very small number. You can force the smaller dimension to the desired width by setting BestFit to true and the second element of ScaleToSize to a very large number.

/StretchToPageSize

The image is scaled anamorphically to fill the area defined by ScaleToSize (if that is not null) or the PageSize in the page device (if ScaleToSize is null ).

/UnitSquare

The image is scaled to fit into a unit square in the current user space. This option is usually used when placing an image onto a page with other graphics. It is deliberately similar to the normal method of processing images in PostScript, by setting the CTM such that the area to be covered by the image is one user unit on each side.