(v13) OPI configuration data
This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP.
Some procedures described in (v13) Making decisions based on preview quality in OPI take a config item on the stack. This can be either a dictionary of configuration values, or the name of a "standard" configuration set.
OPIversions
OPIversions takes an array as an argument. All elements in the array must be real numbers corresponding to supported OPI versions; the RIP supports version 1.3 and 2.0. If comments from more than one OPI version are associated together in a PostScript job file, then the Harlequin RIP uses those from the version that appears first in the OPIversions array.
In PDF jobs, OPI 1.3 and OPI 2.0 comments are not appropriately associated. For PDF jobs: If the job includes both versions of comments and the Harlequin RIP is configured to act on both, the procset acts on OPI 1.3 comments only.
The default value is [ 1.3 2.0 ].
OPIdirectories
This defines where the HqnOPI procset looks for high-resolution image files while replacing images. The value should be an array of file paths. Each file path may include a PostScript-language device name and possibly a directory path. If it is not just a device name, it must be terminated with a slash character ( / ).
You may use two keys rather than strings for special cases:
| The volume and directory path in the OPI comment is acted on, which is subject to the setting of the |
| The high-resolution files are looked for in the same directory as the job file itself. This option is ignored if the job file is being read through an input plug in. |
You can explicitly define that file names should not be mapped by including a slash ( / ) character at the beginning of the name (or immediately after the closing percent ( % ) of the device name if present). This may be useful when searching for files that have been created by processes other than the RIP itself, which is likely to be the case when handling OPI.
For example:
[ (%OPI%) (%E%/OPI/highres/) (/OPI/) ]
Default:
[ (OPI/) ]
OPIdirectories is also used to specify the search locations for external profiles and files for PDF/X-5 files. No attempt is made to locate the file at the exact location specified in the job. The list of search directories is specified using the following form:
<<
/OPIdirectories [ (OPI//) (%Mounted_Drive%/FileLocation// ) ]
>>
/HqnOPI /ProcSet findresource /HqnOPIconfigure get execThis defines two directories on the local file system that are searched for external resources.
All PDF/VT-2 files are also PDF/X files; these comments apply to both URLs from output intents (PDF/X-4p, PDF/X-5pg) and all file specs in reference XObjects (PDF/X-5g, PDF/X-5pg), including URL file specs.
Each entry in the URLs array in an output intent is examined in turn until either a file is found based on the rules described below, or until the end of the array is reached. If no profile is found for any of the URLs, the job aborts with an error.
For each URL from the URLs array, or the first of the F, Mac, DOS, Unix keys in a file spec, processing is performed as follows:
- The scheme and directory path are stripped from the string to leave the file name and extension.
- Each of the entries in the
OPIdirectoriesarray (set through theHqnOPIprocset) is prepended to the file name and extension in turn. The first that includes a file with the name from the URL is assumed to be the intended target file. - For an output intent the checksum of the target file is calculated and compared with the value stored in the output intent. A failure to match means that the wrong ICC profile has been found, and the job aborts.
- For a reference
XObject, the document metadata of the target file is calculated and compared with the values stored in the referenceXObjectmetadata. A failure to match means that the wrong PDF file has been found, and the job aborts.
Global Graphics is considering adding a configuration item to skip the validation of checksums and reference XObject metadata. Validation is useful for formal conformance with the standard and for testing of systems during installation and integration but may have a negative impact on performance in regular production.
The OPIdirectories array may be defined on a job-by-job basis using the HqnOPIconfigure entry to the HqnOPI procset, enabling the use of different directories for files referenced from different jobs. UNC paths may be used in OPIdirectories if they have been previously mounted in the RIP file system (for example, by using ResolveDevice in HqnUNC).
Global Graphics treats all URLs and file specs as being encoded in the native code page of the underlying file system and does not re-encode them. Most file system code pages are aligned with ASCII in the range of character codes defined in RFC1738 (for URLs), but the use of character codes outside of that range may or may not work as expected.
It is assumed that the Digital Front End is responsible for ensuring that all referenced files are available at the correct URLs before the RIP attempts to access them. If a referenced PDF file or ICC profile is not available when the RIP tries to locate it, the job is aborted.
OPIcommentMapping
The OPIcommentMapping key is used when processing a /CommentPath value in OPIdirectories. Each entry in the array should be an array of two strings.
The first string is compared with the start of the file name in the OPI comment. If it matches, directory delimiters in the remainder of the name in the comment are converted from a platform specific encoding into the generic RIP encoding, and the converted remainder is appended to the second value in the OPIcommentMapping sub-array.
The second value in each sub-array must be in the generic filename formatting, as described from (v13) File names, device names, and relative devices. Take care to include a trailing directory delimiter in this second string if there is a trailing directory delimiter in the first string. It is also advisable to disable filename mapping by adding an additional trailing forward slash ( / ) character to the second string.
Thus, for example, if OPIcommentMapping had this value:
[ [ (OPI) (%server/share%OPI/) ] ]
and an %ALDImageID comment were encountered with the filename (OPI:Job123:image.tif, the procset would search for a file matching (%server/share%OPI//Job123/image.tif.
Backslash characters ( \ ) must be escaped with an extra backslash; for example, to encode:
(\\server\share\) you must type (\\\\server\\share\\).
If two mappings are to be included where one is an initial substring of the other and where the mappings ultimately point toward different search directories, you must include the mapping with the longer comparison string first.
Comparison of comments with the search string is case sensitive.
Where none of the supplied mapping comparison strings matches the start of the file name from the comment, the procset attempts to convert the entire filename into the generic RIP encoding. That attempt is unlikely to lead to a positive identification of the correct search directory unless the application generating the PostScript-language or PDF job is running on the same operating system as the RIP installation, and the OPI replacement files are stored on a server volume.
Default: [ ]
OPInextAction
This defines what action should be performed when all OPI data was collected for an image. The value must be the name of a procedure to be called. The following standard actions are defined in the procset, but others may be added. (See (v13) Customizing the OPI procset.)
| The high-resolution data is searched for and any low-resolution data in the main file is ignored if it is found. This is the default action in the Harlequin RIP. |
| The collected data is displayed in the Monitor window of the RIP. This option is provided for debugging purposes only. |
OPIerrorAction
This defines what action should be taken if a high-resolution image cannot be found or if it causes a PostScript error during processing.
The default value of OPIerrorAction is [ /Blank /LowRes /LowRes /LowRes], meaning that the image area is left blank if there is no preview; otherwise, the procset uses the low-resolution data in the main file. See (v13) Making decisions based on preview quality in OPI for details of how these actions are related to preview quality. The RIP can accept a single value if supplied and use that value for all cases.
| Uses the low-resolution data in the main file (in which the OPI comments were read). If no low-resolution data is present, this leaves a blank. This is the default action |
| Leaves the image area blank |
| Fills the image area with a tint, then run the low-resolution image (if present) over the top. This is suitable for generating thumbnails where it is not appropriate to pull in the high-resolution data, but where it is not known whether the incoming job contains low-resolution data or not. |
| Aborts the job |
| Prints a warning image (containing the name of the image required and a brief note of the error found) instead of the required high-resolution image |
When the RIP is processing a PDF/X-1 job, it reports only the first error of each type. The PDF handing options define whether the Harlequin RIP aborts the job or continues and scans for other errors. (See (v13) Files, filters, and devices for details of handling PDF jobs.)
OPIprogress
Reports OPI images found in the System monitor.
OPIenabled
This Boolean flag may be used to disable OPI comment parsing once HqnOPIparse is called. The default value is false, changed to true by calling HqnOPIparse.
OPIdoImageReplacement
This Boolean flag defines whether explicit calls to HqnOPIimage are acted on. The default value is false. This flag must be set to true to enable OPI replacement in PDF jobs and this is the value supplied by the Image replacement page feature.
OPIreplaceFiles
This flag, together with the OPIreportFiles flag, defines whether OPI comments or objects causes image replacement or trigger warnings in the System Monitor and log file.
The default value of OPIreplaceFiles is [ /All /All /All /None ], meaning that substitution of OPI comments in PostScript jobs should always be attempted unless the OPI comments show that the included image data is suitable for final print. See (v13) Making decisions based on preview quality in OPI for details of how these actions are related to preview quality. The RIP can accept a single value if supplied and use that value for all cases.
OPIreplaceFiles can have the following names as values:
| All OPI comments or objects lead to an attempt to insert the high-resolution data. This is the default value. |
| Any OPI comments or data where the extension in the specified file name is included in |
| No image replacement is attempted but see the note for |
Setting OPIreplaceFiles to /None is not the same as setting OPIenabled to false, because it offers the option of reporting OPI requests in the job; also such reports may be triggered from requests in PDF jobs, as well as only covering the parsing of comments in PostScript language jobs as OPIenabled does.
OPIreportFiles
This flag defines what happens when OPI comments or objects are encountered that do not lead to an attempt to insert high-resolution data—because of the value of OPIreplaceFiles.
The default value of OPIreportFiles is [ /Warn /Warn /Ignore /Ignore ], meaning that there is a warning for preview images known to be absent or low-resolution while the comments are ignored silently if the preview images are of unknown or high resolution. See (v13) Making decisions based on preview quality in OPI for details of how these actions are related to preview quality. The RIP can accept a single value if supplied, and use that value for all cases.
OPIreportFiles can have the following names as values:
| Such OPI comments or objects are silently ignored. |
| A warning is issued in the System Monitor and log file, including the name of the file. |
| The job is aborted. |
Warnings and aborts are only acted on if OPIenabled is true for PostScript jobs, and OPIdoImageReplacement is true for PDF files.
OPI_DCSmatch
This Boolean is set to false by default. If both DCS and OPI parsing are being used and the OPIdirectories entry matches the DCSdirectories entry used by the DCS parsing code, it should be set to true to make searching for files more efficient.
OPIfileSearch
The standard file search algorithm may be set to one of three basic modes:
| In this mode, a file with exactly the same name as that specified in the PostScript OPI comments or PDF OPI object is searched for in each of the locations defined in Earlier versions of this manual incorrectly stated that file-name matching is case-insensitive. |
| In this mode, files with the same base name, but possibly with different extensions are searched for. See (v13) OPI file searching - fuzzy name matching on fuzzy name matching for details. This is the default mode, it is recommended over |
| This mode is very similar to |
OPIfavorMatch
This Boolean value is used during file search in /Fuzzy or /Insensitive modes—see (v13) OPI file searching - fuzzy name matching for details. The default value is false.
MultipleMatches (OPI configuration)
This key defines the action taken if the file search finds multiple files that could validly be used to replace a low-resolution file in the job.
| Aborts the job |
| Selects a file and emit a warning on |
| Silently selects a file. |
See (v13) OPI file searching - fuzzy name matching for more details.
OPIlowResFiles
The value of this key is a dictionary listing file extensions that should be regarded as referring to low-resolution files. Each key in the dictionary must be a string, starting with a period (.). The rest of the string must be uppercase letters. The value of each key is ignored and may therefore be anything. The default value is:
<<
(.SMP) dup % Color Central
(.LAY) dup % Helios
(.FPO) dup
(.VIEW) dup
>>The list is used in two places—in fuzzy name matching (see (v13) OPI file searching - fuzzy name matching for more details), and if the value of OPIreplaceFiles is /LowRes .
OPIdebug
This is used for debugging purposes only. It is a set of bit flags, documented in the head of the HqnOPI procset.
OPI2.0Transparent
This key provides control of transparency in images to compensate for some problems with the OPI specification and the behavior of some creating applications.
OPI version 2.0 has no flags to set transparency in a referenced image other than the use of OPIimage, but many applications do not define OPIimage. Additionally, some "high-resolution" files are vector-defined, so OPIimage cannot be used; there is no sensible way to define an OPIimage procedure in a PDF job. OPIimage is ignored by the in-RIP OPI code in the Harlequin RIP.
The OPI2.0Transparent flag may be used to define whether one bit, single-channel image data should be regarded as transparent or not. The following values are supported:
| Always treat as transparent. |
| Treat as transparent if |
| Always treat as opaque. |
PreSeparatedAction (OPI configuration)
If composite (that is, RGB or CMYK) high-resolution data is requested in a pre-separated workflow, or from a DCS separation, then this key controls what happens. See also (v13) Limitations of OPI replacement for a discussion of limitations in using composite data.
The possible values are:
| Abort the job with an |
| Ignore the high-resolution data and use the low-resolution screen preview (if present). |
| Issue a warning and continue regardless. |