@quadient/evolve-impositioning

Impositioning utilities for Quadient Evolve scripts. This package provides a comprehensive set of tools for building impositioning scripts that manipulate TNO file pages, generate commands, and produce bundled output.

Installation

Add to project:

npm install @quadient/evolve-impositioning

Usage

import {
    resolveInputFilePath,
    resolveMetadataFilePath,
    createMetaContext,
    createGroupBeginCommand,
    createCopyInputPageCommand,
    createPageSizeCommand,
    generateCommandFilePath,
    writeCommandFile,
    createBundledGenerateOutput,
} from "@quadient/evolve-impositioning";

API Overview

Metadata Parsing

| Function | Description | |---|---| | createMetaContext(metadata) | Parses raw TNO metadata JSON into a structured MetaContext with groups and page info. | | parsePageSizes(metadata) | Parses page sizes from raw metadata into a PageSizes object. |

Command Building

| Function | Description | |---|---| | createGroupBeginCommand() | Creates a command marking the start of a new document group. | | createCopyInputPageCommand(context, inputFile, pageNumber, transformation?, copySheetNames?, svgPath?) | Creates a command that copies a page from an input file.| | createPageSizeCommand(pageSize) | Creates a command that sets the page size for the current output page. | | createOverrideSheetNameCommand(index, value) | Creates a command overriding a sheet name at the given index. | | createOpticalMarksCommand(opticalMarks, printBarcodeText?) | Creates a command placing barcodes/optical marks on a page. |

Transformation Matrices

2D affine transformations for positioning pages on sheets (used in N-Upper, duplex, etc.):

| Function | Description | |---|---| | createIdentityMatrix() | Returns a 6-element identity transformation matrix [1, 0, 0, 1, 0, 0]. | | applyScale(scale, matrix) | Applies uniform scaling to a transformation matrix. | | applyMove(x, y, matrix) | Applies a translation to a transformation matrix. | | applyRotation(angle, matrix) | Applies rotation (in radians) to a transformation matrix. | | applyRotation180(matrix) | Applies a 180-degree rotation to a transformation matrix. |

File Utilities

| Function | Description | |---|---| | resolveInputFilePath(context) | Resolves the input TNO file path from context parameters or the job output folder. | | resolveMetadataFilePath(context, inputFilePath) | Resolves the metadata JSON file path from context or derives it from the input path. | | resolveOptionalMetadataPath(metadataPath, inputFilePath) | Resolves an optional metadata path, defaulting to inputFilePath + ".json". | | resolveOutputFilePath(context) | Resolves the output file path from context parameters. | | resolveWorkingDirPath(path) | Prepends the working directory prefix to a path. | | generateCommandFilePath() | Generates a unique command JSON file path in the job output folder. ⚠️ Requires the commandOutput input to be registered in getDescription() (see note below). | | writeCommandFile(commands, filePath, context) | Serializes and writes a Commands object to a file. | | normalizePath(path) | Normalizes IPS-style file paths. | | mapToAbsolutePath(path) | Maps a relative path to an absolute path using known prefixes. | | validateMetadataFileExists(file) | Validates that a metadata file exists; returns an error if missing. | | validateMetadataFileExistsWithName(file, fileName) | Validates that a metadata file exists with a custom error message. | | validateFileExists(file, fileName) | Validates that a generic file exists; returns an error if missing. | | isValidString(value) | Checks whether the value is a non-empty string. | | isValidNumber(value) | Checks whether the value is a valid number. | | generateUniqueId() | Generates a unique identifier string. |

generateCommandFilePath() — Required Input

For generateCommandFilePath() to work correctly, the following input must be present in the getDescription() method of your script:

{
    id: "commandOutput",
    displayName: "Command output",
    description: "Command output",
    required: false,
    readonly: true,
    defaultValue: "job://output",
    type: "OutputResource",
},

Without this input the function will not be able to resolve the output folder and will fail at runtime.

Output Generation

| Function | Description | |---|---| | createBundledGenerateOutput(commandFilePath, context, outputPath?) | Creates BundledGenerateOutputV2 using context parameters and a command file. | | createBundledGenerateOutputExplicit(commandFilePath, outputFile, outputType, prodConfigType, prodConfig, context) | Creates BundledGenerateOutputV2 with explicit parameters. |

Barcode Utilities

| Class | Description | |---|---| | QuietZone | Defines the quiet zone padding around a barcode. | | Code39Settings | Configuration for Code39 barcodes (position, size, orientation, ratio, quiet zone). | | DataMatrixSettings | Configuration for DataMatrix barcodes (position, orientation, cell size, quiet zone). | | BarcodeBuilder | Abstract base class for building pages with barcodes. | | ExampleBarcodeBuilder | Concrete builder that creates barcode commands with "Document Identity" and "Page N of M" content. |

Types and Enums

Interfaces: Command, GroupBeginCommand, CopyInputPageCommand, OverrideSheetNameCommand, OpticalMarksCommand, Commands, PageSizes, Group, MetaContext, Metadata, OpticalMarkInfo, BarcodeSettings, BarcodePageInfo

Enums: BarcodeOrientation, DataMatrixOrientation, OpticalMarkType, PageSelection

Building

npm run build

Compiles TypeScript sources from src/ to dist/ using tsc.

Template for a New Script

import {
    type Command,
    type Commands,
    type MetaContext,
    resolveInputFilePath,
    resolveMetadataFilePath,
    validateMetadataFileExists,
    generateCommandFilePath,
    writeCommandFile,
    createBundledGenerateOutput,
    createMetaContext,
    createGroupBeginCommand,
    createCopyInputPageCommand,
    createPageSizeCommand,
} from "@quadient/evolve-impositioning";

export function getDescription() {
    return {
        description: "Description of what this script does.",
        input: [
            {
                id: "inputFilePath",
                displayName: "Input file path",
                description:
                    "Path to the TNO file containing source data. If left empty, the search for the TNO file is performed in the job://output folder.",
                type: "String",
                required: false,
            },
            {
                id: "metadataFilePath",
                displayName: "Metadata file path",
                description:
                    "Path to the metadata file. If left empty, the search for the file is performed in the same location as for the input file with the JSON extension, including the full name of the file (e.g. share://file.tno.json).",
                type: "InputResource",
                required: false,
            },
            {
                id: "outputFilePath",
                displayName: "Output file path",
                description:
                    "Path where the output file will be stored. If undefined, output will be stored in the same location as the input file using the extension of the selected output type. Note that in such a case, the input file may be overwritten.",
                type: "String",
                required: false,
            },
            {
                id: "outputType",
                displayName: "Output type",
                description: "Desired output type. InspireNative represents the Final Production.",
                type: "Selection",
                options: [
                    "PDF",
                    "AFP",
                    "InspireNative",
                    "InspireNativeIntermediate",
                    "MTIFF",
                    "PCL",
                    "AdobePostScript2",
                    "AdobePostScript3",
                    "EPS",
                ],
                required: true,
                defaultValue: "InspireNative",
            },
            {
                id: "productionConfigurationType",
                displayName: "Production configuration prefix",
                description: "Prefix (type) locating the production configuration file.",
                type: "Selection",
                options: ["Icm", "IcmSampleSolutions", "IcmCustomSolutions", "Custom"],
                required: false,
                defaultValue: "Custom",
            },
            {
                id: "productionConfiguration",
                displayName: "Production configuration",
                description: "Path to production configuration file following the prefix (type).",
                type: "String",
                required: false,
            },
            {
                id: "commandOutput",
                displayName: "Command output",
                description: "Command output",
                type: "OutputResource",
                required: false,
                readonly: true,
                defaultValue: "job://output",
            },
        ],
        output: [
            {
                id: "impositioningGenerate",
                displayName: "Impositioning bundle",
                description: "Bundles the generate step.",
                type: "BundledGenerateArray",
            },
        ],
    } as const satisfies ScriptDescription;
}

export async function execute(context: Context): Promise<Output> {
    // 1. Resolve paths
    const inputFilePath = await resolveInputFilePath(context);
    const metadataFilePath = resolveMetadataFilePath(context, inputFilePath);

    // 2. Read and validate metadata
    const metadataFile = context.getFile(metadataFilePath);
    await validateMetadataFileExists(metadataFile);
    const metadataJson = JSON.parse(await metadataFile.read());

    // 3. Parse metadata
    const metaContext = createMetaContext(metadataJson);

    // 4. Build commands
    const commands = buildCommands(metaContext, inputFilePath, context);

    // 5. Write and return
    const commandFilePath = generateCommandFilePath();
    await writeCommandFile(commands, commandFilePath, context);

    return {
        impositioningGenerate: [await createBundledGenerateOutput(commandFilePath, context)],
    };
}

function buildCommands(metaContext: MetaContext, inputFileName: string, context: Context): Commands {
    const pages: Command[][] = [];

    for (const group of metaContext.groups) {
        for (let i = 0; i < group.pageSizes.length; i++) {
            const newPage: Command[] = [];

            if (i === 0) {
                newPage.push(createGroupBeginCommand());
            }

            newPage.push(createCopyInputPageCommand(context, inputFileName, group.pageNumbers[i]));
            newPage.push(createPageSizeCommand(group.pageSizes[i]));
            pages.push(newPage);
        }
    }

    return { pages };
}