Harlequin VariData parameters
To view previous v13.x documentation, go to Manuals (v13).
This page applies to Harlequin v14.0r0 and later; and to Harlequin Core but not Harlequin MultiRIP.
Page content:
This section describes the various PDF parameters that can be used with HVD.
Unless otherwise stated, these parameters may be set in pdfopen, setpdfparams, or pdfexec; they cannot be set in pdfexecid.
Also, unless otherwise stated, the above parameters apply to both internal and external mode, including position independent.
When using external HVD (eHVD) it is usually also necessary to set the /ContoneMask pagedevice parameter, see ContoneMask (page device).
EnableOptimizedPDFScan
Optional
Boolean or name or string
Default: /Never
Activates Harlequin VariData.
/EnableOptimizedPDFScan can be used as a tri-state parameter allowing: /Always , /Never , or /Auto while also retaining the Boolean options of true and false for backwards compatibility, where /Always is the same as true and /Never is the same as false.
OptimizedPDFCacheID
Required
String
This key is required when HVD is activated and is the identifier for the cache implementation to connect to (that is, it identifies the HVD back end that is to be used to perform raster element caching). It may be one of the built-in values (prefixed with GG_ ) or one defined by a custom OEM created back-end cache implementation. This could be a plugin, an HHR back end (see Output methods) or internal HVD (GGIRR).
The value used should be a unique string; we recommend that you prefix it with an abbreviation that identifies your company or product (for example: OEM_HHR_PDF_HVD).
For more information, see eHVD diagnostic mode.
OptimizedPDFCoalesceLimitPercent
Optional
Integer
Default: -1
This option provides less scanning flexibility and controls the way marks on the page are coalesced into raster elements. If this parameter is negative (that is, the default), there is no restriction: every eligible mark is coalesced. If it is zero, no coalescing at all takes place. If it is positive, coalescing is allowed.
The higher the value, the more likely a mark is allowed to coalesce with other marks despite any growth in the overall bounding box it may lead to. Conversely, a small positive value means that coalescing happens only in those cases where there is little overall increase in the overall bounding box. In other words, large values of this parameter are likely to mean fewer elements per page, but larger areas of white space within them.
OptimizedPDFCoverageLimitPercent
Optional
Integer
Default: 0 (no limit)
This option can only be used for eHVD.
This option only takes effect when OptimizedPDFExternal is true. When greater than zero, the RIP calculates the total area of the bounding boxes of the raster elements it has scanned on every page. When this area expressed as a percentage of the overall page area exceeds the value of this parameter, all marks for the page in question are coalesced into a single raster element. For example, if the scanner calculates that there are three elements on a given page and each is the same size as the page itself, the calculated total area is 300% of the page area; any value below 300 for this parameter would result in the page being limited to a single raster element (and thus the coverage would be reduced to 100%).
OptimizedPDFElementTileClip
Optional
Boolean
Default: false
A boolean that only has effect when both HVDPage and HVDElement methods are defined in The settilingparams operator. It determines if HVDElement tiling is clipped to the bounding box of each HVDPage tile. The default value (false) allows elements to be reused between HVDPage tiles; however, doing so may result in more elements intersecting a particular HVDPage tile and having odd intersections with HVDPage tiles (depending on the element position).
Setting this value to true reduces the chance of being able to reuse elements between HVDPage tiles; however, doing so may result in fewer elements intersecting each tile.
OptimizedPDFExternal
Optional
Boolean
Default: false
This controls whether external or internal HVD is used. When this PDF parameter is true, external HVD is used, and the RIP assumes that the OEM’s own code has a method to store and combine the output rasters to form a final page.
OptimizedPDFFormIntersectPixels
Optional
Integer
Default: 3
Number of device pixels to relax intersection test by for forms that are repeated multiple times on a single page.
Jobs printing elements such as labels or imposed postcards can have a few pixels of overlap between repeats of those elements. If the elements are transparent or contain transparent items, HVD would normally coalesce adjacent instances, even if they only overlap by a few pixels.
This parameter is for preventing such coalescing where the overlap is sufficiently small that it can be regarded as not being deliberate.
Using a large value runs the risk of processing deliberate overlaps incorrectly, but the maximum appropriate value depends on device resolution and the jobs being processed. Valid values are integers. 0 means to not relax the intersection test.
OptimizedPDFFormThreshold
Optional
Integer
Default: 512
This parameter sets the minimum stream length in bytes for an XObject form to be automatically treated as significant (and hence more likely to be retained) the second time it is encountered. This avoids forms which are, for example, just containers for very small fills or linework automatically being treated as significant, and can help avoid an excessive number of small rasters being retained. If the form contains significant marks or is being treated as significant (for example, due to PDF/VT hints), this parameter makes no difference.
The value for OptimizedPDFFormThreshold is set in bytes, while the value for OptimizedPDFImageThreshold is set in kB.
OptimizedPDFGridEpsilon
Optional
Real number
Default: 0.000001
This option only applies to position-independent eHVD.
This option only takes effect when used with position-independent eHVD. It has no effect when either /OptimizedPDFExternal or /OptimizedPDFPositionIndependent is false.
This controls how sensitive HVD is to differences between the phase offsets of graphics with respect to the pixel grid. The smaller, the more sensitive, and more likely that eHVD output exactly matches rendering without HVD. The larger the value, the more likely the RIP is to identify two elements as identical and therefore to increase performance.
Positive real values up to a maximum of 1.0 can be used (or the integer value 1); for many applications we recommend a value of 1.0 as giving sufficiently accurate output.
Maximum valid value: 1.0 or 1
A value of 0 is taken to mean the default value.
OptimizedPDFGridX, OptimizedPDFGridY
Optional
Real numbers
Default: 1.0
This option can only be used for eHVD.
This pair of parameters controls the grid size from which the HVD scanner calculates phase offsets. It is expressed in device pixels. By default this grid is set on single-device pixel boundaries but, for instance, if a customer code requirement exists where raster elements must be aligned on a grid which is larger than that, these parameters may be adjusted. Naturally, the larger these values are, the greater the probability that two elements which differ only in x ,y offset is given different ID values.
The values entered are rounded to the equivalent of the nearest positive integer (that is, a value of 4.2 is rounded to 4.0).
OptimizedPDFIgnoreHints
Optional
Boolean
Default: false
When set to true, all GTS and GGSL hint entries in XObjects are ignored. It is provided primarily for debugging files and for cases where hints have been set incorrectly. See Harlequin Technical Note Hqn101: Harlequin VariData hint tags.
OptimizedPDFIgnorePatternPhase
Optional
Boolean
Default: false
This option only applies to position-independent eHVD.
If /OptimizedPDFIgnorePatternPhase is set to false, the RIP respects the standard PDF pattern phase rule, so the output is the same as without HVD. This is likely to result in some loss of reuse, compared to setting /OptimizedPDFIgnorePatternPhase to true, as the placement of the pattern depends on the position of the patterned object.
If /OptimizedPDFIgnorePatternPhase is set to true, the RIP reuses patterned objects independent of position, which may mean that output is different from what it would have been without HVD and patterns may have discontinuities between two adjacent objects using the same pattern.
OptimizedPDFImageThreshold
Optional
Integer
Default: 32
This parameter sets the minimum stream length in kB for an image (or imagemask) XObject to be automatically treated as significant (and more likely to be retained). This can help avoid an excessive number of small rasters being retained.
The value for OptimizedPDFFormThreshold is set in bytes, while the value for OptimizedPDFImageThreshold is set in kB.
OptimizedPDFPositionIndependent
Optional
Boolean
Default: true
This option can only be used for eHVD.
This boolean flag, when set, enables position independent HVD. When in position-independent HVD mode, the RIP finds elements that appear on multiple pages drawn with gstates which are identical except for their x ,y translation values. That is, the elements passed to the customer code have extra position data alongside them, which is needed to reassemble the final page from the elements supplied by the RIP.
For example, a 2 x 2 imposed flat where each of the imposed pages has the same background uses a single cached element to represent that background; it appears four times in the API metadata for that page, each time with a different x ,y offset. When this flag is false, each element passed to the customer code by the RIP is the same size as the pages for which the element is intended. When it is true, each element is passed in a raster that is just large enough to contain the data. That is, none of the elements making up a page are necessarily the same size as the page.
The raster and metadata delivery to the back end is different between plain eHVD and position independent eHVD; see eHVD API.
OptimizedPDFScanChunkSize1
Optional
Boolean
Default: false
When iHVD or NPI-eHVD are in effect, setting this parameter to true allows the HVD scan to take place with a chunk size of 1.
In combination with the /OptimizedStashPages parameter, this may allow reuse to take place for a multi-page job even with a chunk size as low as 1. In addition in a few cases, multi-page iHVD or NPI-eHVD jobs with suitable GGSL hints may reuse with a chunk size of 1. The parameter has no effect where the RIP is presented with a longer job or a bigger chunk size.
Before v14.0, when PI-eHVD is in effect with /OptimizedPDFIgnorePatternPhase false and the RIP detects patterns in the job, it would drop back to NPI-eHVD internally, in which case this parameter would prevent a single-page chunk from aborting the scan.
From v14.0 onwards, this parameter has no effect when PI-eHVD is in use.
OptimizedPDFScanLimitPercent
Optional
Integer percentage
Default: 10
An integer percentage (that is, min. 0, max. 100). It controls whether the optimized PDF scan ends early or not.
This value is present to avoid the scanning overhead on jobs where the optimization is not going to be effective. The HVD scanning phase checks whether any reuse has been found on each page, and if not, then this page is considered a unique page. The accumulated number of unique pages in the current file (or chunk if PageRange is being used) so far is compared to the total number of pages in the file/chunk. If the percentage exceeds the OptimizedPDFScanLimitPercent the scan is aborted and the rest of the processing of the file/chunk is performed without HVD.
If position-independent HVD is not in use, the scanning is omitted entirely if 100 / (pages in chunk) > OptimizedPDFScanLimitPercent, as each element can be (re)-used at most once per page. For example, if the OptimizedPDFScanLimitPercent is 25, then scanning would not be started for a file/chunk with fewer than four pages.
If a large job is split into “chunks” of data with the use of /PageRange (see Using HVD with page ranges), and the HVD scan in any chunk aborts because too many unique pages are encountered, then no scan at all is tried for any subsequent chunk in the job. Thus, if you are using small chunks of data and are seeing jobs aborting the HVD scan when you think there should be re-use of data, you should consider increasing the /OptimizedPDFScanLimitPercent value, possibly up to the maximum of 100% (in which case the HVD scan continues for the whole job).
This does not mean that the scanner scans the specified percentage of pages in the job. If the scan determines that the job benefits from HVD, then all pages are scanned.
OptimizedPDFSetupID
Optional
String
Default: ()
A string to enable different RIP configurations to be distinguished.
The value used should be a unique string; we recommend that you prefix it with an abbreviation that identifies your company or product (for example, OEM_HHR_PDF_HVD).
This option can be used for both eHVD and iHVD. Its value is a string that affects the hashes of all the rasters produced. If rasters are retained between jobs, but the page setup changes in a way that may affect output, this value should change. This is to avoid a later job erroneously picking up an unsuitable raster that was created for an earlier job (for example, /OptimizedPDFSetupID (27B)).
OptimizedPDFSingleForeground
Optional
Boolean
Default: false
This option can only be used for eHVD.
This parameter only takes effect when /OptimizedPDFExternal is in use. It ensures that (when tiling is not in use) pages are split into at most two raster elements (that is, a background element and a foreground element, which when combined provide the full page content).
In addition, if a page needs to be initialized to a color other than white, a page background_id element is produced.
Setting this value to true tends to reduce reuse, although this depends on the job.
true when tiling is in use.
OptimizedPDFStashPages
Optional
Integer
Default: 0, values outside the range [0, 32] are limited to being inside the range. (This restriction may change in future.)
This parameter applies to all types of HVD and is useful when running jobs in small pdfexecid chunks.
When jobs are run in pdfexecid chunks in the absence of this parameter (or when the parameter value is 0), although rasters stored in one chunk may be reused in a later chunk, the scanning of each chunk starts afresh as if there had been no previous chunks. With a non-zero parameter set here, the RIP retains much of the scan information relating to pages from chunks before the one it is currently scanning.
This means that the scan tends to be faster, since there should be no need to rescan objects which are already known and which will have the same appearance, and in addition it is sometimes possible to make better reuse decisions based on information retained from previous pdfexecid chunks.
For example, when running a job for which the static data on the odd pages is different from those on the even pages, it may be decided to set a chunk size of 4. Setting a parameter value of 2 would mean that scan information is available for both an odd and an even page from the previous chunk, thereby likely speeding up the current chunk. If running a job with more than 1 rip with a proposed chunk size < 2 * the repetition period, (so with a proposed chunksize < 4 in this case), it will generally be better to set a somewhat higher parameter value.
This parameter does not have any effect for jobs that are run in pdfexec chunks.
This parameter also enables many more HVD jobs to reuse with a chunk size of 1 (although it is often faster to run with a larger chunk size).
In the case of iHVD and NPI-eHVD, the following parameter must be set in addition to /OptimizedPDFStashPages in order to avoid the RIP aborting the scan for a one-page chunk:
/OptimizedPDFScanChunkSize1 true
OptimizedPDFTestOpaqueHint
Optional
Boolean
Default: true
When set to true, a true value for the GGSL_Opaque hint key in an XObject is ignored. If OptimizedPDFTestOpaqueHint is set to false, then a true value for GGSL_Opaque is acted on. The OptimizedPDFTestOpaqueHint has no effect when the GGSL_Opaque hint has a value of false . See Harlequin Technical Note Hqn101: Harlequin VariData hint tags.