(v13) Defining HqnImpose2 mark sets

This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP.

Individual marks may be defined as dictionaries within the Marks array as described above. As from Harlequin 12, it’s also possible to define mark sets. This is most useful when the main page being rendered includes multiple instances of some form of design, (for example, multiple labels, tickets, or cartons).

A set of marks may be defined that overlays one or more marks on one of those instances, which is then replicated across all other instances.

To do this, define the /MarkSets key in the configuration dictionary provided to HqnInitImpose or HqnInitOverlay. The value of MarkSets must be an array of one or more dictionaries. This array must be in global VM.

Each of those dictionaries may contain the entries shown in the following table:

Individual marks	Notes and other keys
`Enabled`	Optional, Boolean. Should this mark be drawn? Default = `true`
`OverlayGeometry`	Required, array of dictionaries; see below.
`SetMarks`	Required, array of dictionaries; see below.
`MarkContentArrays`	Required if any `MarkSet` content uses `Type=Array` and a name is used for the value of `Array` , otherwise ignored. Dictionary of arrays. Arrays from which mark content may be selected.
`MarkContentDicts`	Required if any `MarkSet` content uses `Type=Dict` and a name is used for the value of `Dict` , otherwise ignored. Dictionary of dictionaries from which mark content may be selected.
`DynamicSource`	Required if any `MarkSet` content uses `Type=Dynamic` with name `Source` value, otherwise, it is ignored. Definitions of dynamic data sources for marks. This includes sources such as `CSV` and automatically processed `Counters`
`MarkID`	Optional, but recommended for debugging purposes, string. If a mark dictionary within `MarkSets` includes a `MarkID` entry, then the string value is reported in any error message triggered while processing that mark.

Table: Entries in dictionaries within the MarkSets array

The value of OverlayGeometry must be an array of one or more dictionaries, each of which contains the following entries:

OverlayGeometry value entry	Notes
`/X`, `/Y`	Required, numbers in points. The X and Y location on the sheet of the origin of this instance of the design. The original is simply and identifiable point within the design, if the design is rectangular, this is normally the lower-left corner, but it doesn't need to be. If X or Y is negative, then they may be used as an offset from the right or top edge of the sheet instead of placing the geometry off the left or bottom edge; it depends on the value of `AllowNegativeMarkOffset`.
`/AllowNegativeMarkOffset`	Optional, Boolean. If X or Y is negative, then they are used as an offset from the right or top edge of the sheet if `AllowNegativeMarkOffset` is `false`. If it’s `true`, the geometry is placed off the left or bottom edge of the sheet. Default = `false`.
`/Angle`	Required, number in degrees. The angle by which this instance of the design is rotated on the sheet. In most cases this can be 0°, but it probably varies between marks if the designs are nested cartons, for instance.
`/GeometrySources`	Normally Optional, but Required if a `SetMark` mark within the same `MarkSet` uses a data source with `Type=/Dynamic` and the value of `Source` is an integer. Array of names. A list of the entries within the `DynamicSources` dictionary in the current `MarkSet` that should be updated at the end of processing this mark.
`/Placement`	Optional, boolean. If the `OneUp` objective is used with the Placement strategy, any `OverlayGeometry` dictionary in which Placement is set to `true` has the X, Y, and Angle values set automatically to reflect the position and placement of the page. Marks are normally positioned relative to the sheet; this functionality allows marks to be placed relative to the page.

Table: OverlayGeometry value entries

The value of SetMarks must be an array of one or more mark dictionaries, very similar to those used in the Marks array in the main configuration dictionary passed to HqnInitImpose or HqnInitOverlay.

Marks and SetMarks vary in the following ways:

The values of X and Y on a MarkSet mark are not locations on the whole sheet, but are distances from the origin of the overlay geometry instance being processed. Negative values always mean a location to the left or below the origin.
The values of certain mark parameters may be set dynamically using data sources. Some constructs may only be used in marks in a MarkSet , and not in marks in the Marks array. This includes:Data sources with Type=/DynamicData sources with Type=/Array and a name value for /Array.Data sources with Type=/Dict and a name value for /Dict.

Processing sequence

When processing marks for an overlay, marks are handled in the order described in the following pseudo code:

            For each entry in the MarkSets array {
                    For each entry in the OverlayGeometry array { For each entry in the SetMarks array {
                        Draw the mark
                    }
                        For each entry in the GeometrySources array { Load the next value/record
                    }
                }
            }
                For each entry in the Marks array { Draw the mark
            }

Dynamic marks values are updated at the beginning of every OverlayGeometry array. This means:

For CSV marks the next record is read from the source CSV file.
For Counter marks, the Value is incremented or decremented and then reset as specified by the other keys in the DynamicSources dictionary.