Feature: Add -d switch to printtarg for custom target label string #19

New Issue

2026-08-28T17:56:31+01:00

gronod commented

2026-08-28 17:56:31 +01:00

Summary

Add a command-line switch -d "<string>" to printtarg allowing users to supply a custom description/label string to be printed along the page/strip borders on generated test target files (TIFF, PostScript, EPS), replacing the default generated chart identifier label.

Motivation & Background

Currently, printtarg automatically constructs a hardcoded label for each target page/strip in target/printtarg.c:

sprintf(label, "ArgyllCMS - Chart \"%s\" (%s %d) %s",
        psname, rand ? "Random Start" : "Chart ID", rstart, atm);

This text is rendered along the target borders using tro->vstring(...). In automated profiling workflows, frontends (such as ICCery), proofing suites, and custom calibration jobs, users frequently need to annotate charts with specific profile names, media types, printer settings, or custom identifiers, or omit the text altogether.

Command-Line Switch Selection

Proposed Switch: -d "<string>"
Rationale:
- -d is currently unused in printtarg (-D is used for 8-bit TIFF dithering).
- Consistent with ArgyllCMS conventions across other tools (e.g., -D in colprof, collink, cctiff for descriptions/display labels).
- Intuitive and mnemonic for Description / Display label.
- Alternatives evaluated: -l (easily confused with 1 or I), -L (already used for suppressing left border), -B/-H (less standard).

Technical Specification & Implementation Plan

1. CLI Parsing (`target/printtarg.c`)

Add a handler for -d in main() argument parsing:

/* Custom chart label string */
else if (argv[fa][1] == 'd') {
    fa = nfa;
    if (na == NULL) usage("Expected string argument to -d");
    custom_label = na;
}

If -d is provided:
- If custom_label is non-empty, use custom_label directly as label.
- If custom_label is empty (-d ""), disable label drawing (dopglabel = 0; dorspace = 0; or skip tro->vstring calls), fulfilling the to-do item at printtarg.c:L30 ("Add option to omit labelling").
If -d is omitted, retain the current default sprintf(label, ...).

2. Constraints, Edge Cases & Pitfalls

Buffer Size & Truncation:
- label buffer in printtarg.c is currently char label[400].
- Update label buffer allocation to at least 1024 bytes and use bounded copies (strncpy/snprintf) to guard against arbitrary command-line input lengths.
PostScript Escaping:
- ps_vstring() wraps strings in parentheses: (%s).
- Special characters like (, ), \ must be properly escaped (\(, \), \\) before emitting to PostScript to prevent PostScript syntax errors.
- Reject or sanitize newlines/carriage returns (\n, \r, \t) which can break PostScript line structuring.
TIFF / 2D Raster Font Limitations:
- add_string2d() uses the built-in 7-bit ASCII font (timesr_b).
- Non-ASCII or UTF-8 multi-byte characters should be validated/sanitized to prevent missing glyph artifacts or layout calculation bugs.
Page Height & Text Overflow:
- Labels are rendered vertically along the page height y2 - y1.
- A maximum length of ~100–120 characters is recommended for standard page formats (A4/Letter) to prevent text clipping at page boundaries or overlap with corner fiducial marks.
CGATS .ti2 Metadata Integration:
- Store the custom label in the generated .ti2 CGATS file under the DESCRIPTOR or CHART_LABEL keyword for traceability across downstream tools (chartread, colprof).

Documentation Updates Required

target/printtarg.c: Update usage() function banner.
doc/printtarg.html:
- Add -d "<description>" entry to the summary table and usage details section.
- Note escaping rules and behavior when passing empty strings (-d "").
doc/ArgyllDoc.html: Update printtarg summary listing.
doc/ChangesSummary.html & log.txt: Document the new -d switch under the latest version change notes.

Acceptance Criteria

printtarg -d "My Custom Media - 1440dpi" ... generates TIFF, PS, and EPS charts displaying the custom string.
printtarg -d "" ... omits the page/strip label without layout disruption.
PostScript output with special characters (e.g. -d "Test (Sample #1) & 100% Gloss") parses cleanly without PostScript interpreter errors.
Documentation and CLI usage messages are updated.

### Summary Add a command-line switch `-d "<string>"` to `printtarg` allowing users to supply a custom description/label string to be printed along the page/strip borders on generated test target files (TIFF, PostScript, EPS), replacing the default generated chart identifier label. --- ### Motivation & Background Currently, `printtarg` automatically constructs a hardcoded label for each target page/strip in `target/printtarg.c`: ```c sprintf(label, "ArgyllCMS - Chart \"%s\" (%s %d) %s", psname, rand ? "Random Start" : "Chart ID", rstart, atm); ``` This text is rendered along the target borders using `tro->vstring(...)`. In automated profiling workflows, frontends (such as ICCery), proofing suites, and custom calibration jobs, users frequently need to annotate charts with specific profile names, media types, printer settings, or custom identifiers, or omit the text altogether. --- ### Command-Line Switch Selection * **Proposed Switch:** `-d "<string>"` * **Rationale:** * `-d` is currently unused in `printtarg` (`-D` is used for 8-bit TIFF dithering). * Consistent with ArgyllCMS conventions across other tools (e.g., `-D` in `colprof`, `collink`, `cctiff` for descriptions/display labels). * Intuitive and mnemonic for **D**escription / **D**isplay label. * Alternatives evaluated: `-l` (easily confused with `1` or `I`), `-L` (already used for suppressing left border), `-B`/`-H` (less standard). --- ### Technical Specification & Implementation Plan #### 1. CLI Parsing (`target/printtarg.c`) - Add a handler for `-d` in `main()` argument parsing: ```c /* Custom chart label string */ else if (argv[fa][1] == 'd') { fa = nfa; if (na == NULL) usage("Expected string argument to -d"); custom_label = na; } ``` - If `-d` is provided: - If `custom_label` is non-empty, use `custom_label` directly as `label`. - If `custom_label` is empty (`-d ""`), disable label drawing (`dopglabel = 0; dorspace = 0;` or skip `tro->vstring` calls), fulfilling the to-do item at `printtarg.c:L30` ("Add option to omit labelling"). - If `-d` is omitted, retain the current default `sprintf(label, ...)`. #### 2. Constraints, Edge Cases & Pitfalls - **Buffer Size & Truncation:** - `label` buffer in `printtarg.c` is currently `char label[400]`. - Update `label` buffer allocation to at least 1024 bytes and use bounded copies (`strncpy`/`snprintf`) to guard against arbitrary command-line input lengths. - **PostScript Escaping:** - `ps_vstring()` wraps strings in parentheses: `(%s)`. - Special characters like `(`, `)`, `\` must be properly escaped (`\(`, `\)`, `\\`) before emitting to PostScript to prevent PostScript syntax errors. - Reject or sanitize newlines/carriage returns (`\n`, `\r`, `\t`) which can break PostScript line structuring. - **TIFF / 2D Raster Font Limitations:** - `add_string2d()` uses the built-in 7-bit ASCII font (`timesr_b`). - Non-ASCII or UTF-8 multi-byte characters should be validated/sanitized to prevent missing glyph artifacts or layout calculation bugs. - **Page Height & Text Overflow:** - Labels are rendered vertically along the page height `y2 - y1`. - A maximum length of ~100–120 characters is recommended for standard page formats (A4/Letter) to prevent text clipping at page boundaries or overlap with corner fiducial marks. - **CGATS `.ti2` Metadata Integration:** - Store the custom label in the generated `.ti2` CGATS file under the `DESCRIPTOR` or `CHART_LABEL` keyword for traceability across downstream tools (`chartread`, `colprof`). --- ### Documentation Updates Required 1. **`target/printtarg.c`**: Update `usage()` function banner. 2. **`doc/printtarg.html`**: - Add `-d "<description>"` entry to the summary table and usage details section. - Note escaping rules and behavior when passing empty strings (`-d ""`). 3. **`doc/ArgyllDoc.html`**: Update `printtarg` summary listing. 4. **`doc/ChangesSummary.html` & `log.txt`**: Document the new `-d` switch under the latest version change notes. --- ### Acceptance Criteria - [ ] `printtarg -d "My Custom Media - 1440dpi" ...` generates TIFF, PS, and EPS charts displaying the custom string. - [ ] `printtarg -d "" ...` omits the page/strip label without layout disruption. - [ ] PostScript output with special characters (e.g. `-d "Test (Sample #1) & 100% Gloss"`) parses cleanly without PostScript interpreter errors. - [ ] Documentation and CLI usage messages are updated.

gronod added the Kind/Feature

Reviewed

Confirmed

1

labels 2026-08-28 17:56:31 +01:00

gronod referenced this issue from gronod/ICCery

2026-08-28 18:09:10 +01:00

Feature: Custom target label metadata input & generation in Stage 2 (printtarg -d) #119

gronod added a new dependency 2026-08-28 19:06:42 +01:00

gronod/ICCery#119 - Feature: Custom target label metadata input & generation in Stage 2 (printtarg -d)

gronod referenced this issue from a commit

2026-08-28 20:01:52 +01:00