CPTHSV(1)

💖 CPTHSV(1) — the hue/sat/value glow-up page 💖

okay bestie, welcome to cpthsv, a lil User commands utility that ✨modifies hue, saturation and colour value of GMT colour palette tables✨. she's giving palette makeover artist, and honestly? iconic.

---

✨ SYNOPSIS ✨

cpthsv -T transform [-h] [-m model] [-o path] [-v] [-V] [-z] [-Z] [-4]
       [-5] [-6] [path]

---

🦋 DESCRIPTION 🦋

so here's the vibe: cpthsv reads a colour palette, converts its colours to HSV (if needed), messes with those values in some simple ways, converts back to the original colour-space (if needed), and writes the result. so basically she can (de)saturate, brighten, darken or hue-shift. periodt. 💅

ngl, right now only RGB and HSV colour-spaces get transformed — other spaces and fill-types just pass through without being modified, no touchy. (the --verbose option will report the number of segments transformed, so you can vibe check how much actually happened. 👀)

the program reads from stdin if a file is not specified as the final argument, and writes to stdout if the --output option is not specified. super chill, no pressure.

the hue value is taken to be between 0 and 360, while the saturation and value components are taken to be between 0 and 1. 🎀

---

👑 OPTIONS 👑

• --backtrace-file path — specify a file to which to write a formatted backtrace. the file will only be created if there is a backtrace created, typically when an error occurs. (so like, a receipts file for when things go wrong 😭)
• --backtrace-format format — specify the format of the backtrace written to the files specified by --backtrace-file, one of plain, xml or json.
• --comments-read path — read the comments from the specified path and add them to the output gradient.

the format is simply a plain text multi-line document without any comment delimiters (those will be added by the program). she adds the sparkle for you ✨

• --comments-write path — write the comments in the input to the specified path.
• --comments-retain — use the comments in the input file as the comments for the output file. keeping the lore intact fr fr.
• --comments-generate — create a comment with summary data (the date of creation, name and version of the cptutils package) in the output file. a lil birth certificate for your palette 🍼
• -h, --help — brief help. she's got you 🫶
• --hinge value — specify the z-value of the hinge in the cpt file. if there is no hinge directive (i.e., a SOFT_HINGE or HARD_HINGE) in the input, then this option has no effect. 💀

when normalising (with the --z-normalise option), this gives the z-value in the input which is mapped to zero. that z-value must be one of the stops in the input.

when denormalising (with the --z-denormalise option), this gives the value in the output to which zero in the input is mapped. this option can be viewed as the counterpart to the +hvalue appended to the -C option for the makecpt(1).

• --hinge-active — if the input cpt has a SOFT_HINGE directive, then activate that hinge (resulting in independent scaling of the two halves of the gradient either side of the hinge).

if the input does not have such a directive, then this option has no effect. (she said what she said 🙈)

• -m, --model model — on writing the output, convert all colours to the specified model, one of "rgb" or "hsv". this has no effect on non-colour segments.
• -o, --output path — write the output to path, rather than stdout.
• -T, --transform string — specify a transformation to perform. one of h, s or v followed by a number and optional operation. the effect of the number depends on the operation: one of x (multiply by number), % (scale by percentage) or +/- (add or subtract value). an RGB colour with saturation 0.5 would be transformed to one with saturation 0.55 by applying s1.1x or s110% or s0.05+. if the operator is not given then % is assumed.

transformations which take colours outside the HSV colour-space are permitted, the result is truncation (eg, increasing a saturation of 0.8 with s0.3+ results in a saturation of 1.0). the exception is hue: if the hues at each end of a segment are both transformed outside the 0–360 range, they are reduced modulo 360; if only one is then the segment is split in two at the boundary (either 0 or 360) and the segment outside 0–360 reduced modulo 360 to bring it back within.

multiple transforms can be applied by separating transforms with commas. this is to be preferred over multiple calls to the program since the conversion between colour-spaces is necessarily lossy. 😭 multiple transformations are applied in the order given in the argument.

• -v, --verbose — verbose operation. she'll narrate 🗣️
• -V, --version — version information.
• -z, --z-normalise — normalise the z-values in the cpt output into the range 0/1 (or to -1/1 if a hinge is present) and add a RANGE directive if not present in the input. this is the form used in GMT master files.

this option requires that output cpt version is at least 5. don't skip this bestie, it WILL matter.

• -Z, --z-denormalise — set the z-values in the cpt output into the range given by the RANGE directive, and remove that directive. if there is no RANGE then this option does nothing. (yes, literally nothing. the audacity 🍓)
• -4, --gmt4 — use GMT 4 conventions when writing the cpt output: the colour-model code is uppercase, and the colours are separated by spaces.

this is incompatible with the -5 and -6 options of course. 💀

at present this option is the default, but that will change at some point. so specify this option if your use of the output depends on the GMT 4 layout (consumed by a custom parser, for example). future-you will thank present-you, no cap.

• -5, --gmt5 — use GMT 5 conventions when writing the cpt output: the colour-model code is lowercase, and the colours are separated by a solidus for RGB, CMYK, by a dash for HSV.

this is incompatible with the -4 and -6 options of course.

• -6, --gmt6 — as the -5 option, but allows the HARD_HINGE and SOFT_HINGE directives in place of the explicit HINGE = directive.

this is incompatible with the -4 and -5 options of course.

---

🌈 EXAMPLE 🌈

lighten by 10% and desaturate by 20% — the classic combo, ate:

cpthsv -v -T s80,v110 -o new.cpt old.cpt

---

🧚 AUTHOR 🧚

J.J. Green — legend behaviour, honestly 👑

---

this was the cptutils 1.82 era, dated 9 July 2024, and yes she's still the moment. mwah 💋✨💖