CPTCLIP(1)

💖 CPTCLIP(1) 💖

okay bestie, welcome to cptclip, a lil user command from the cptutils crew 🎀 — it lives in section 1 of the manual, iykyk.

---

✨ NAME ✨

cptclip — extract a sub-table from a GMT colour palette table (cpt). 💅

---

🌸 SYNOPSIS 🌸

cptclip -R min/max [-h] [-m model] [-o path] [-s] [-v] [-V] [-z] [-Z]
        [-4] [-5] [-6] [path]

---

🦋 DESCRIPTION 🦋

So the cptclip utility literally just extracts a sub-table out of a cpt format file. That's the whole vibe. 🫶

The arguments to the mandatory --range option, min/max, are interpreted as the (z) limits of the output — unless the --segments switch is specified, in which case they're the segment numbers instead. Two totally different meanings, one option, no cap. 💀

Heads up: if the input has a hinge and the selected clipping range does not include that hinge, then it gets removed in the output. Bye hinge 👋

The program will read from stdin if a file is not specified as the final argument, and write to stdout if the --output option is not specified. Classic. 🧚

Alsooo, note that some of the functionality of this program is included in recent versions of the GMT program makecpt(1). Just saying. 👑

---

💅 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, don't panic if it's not there. 🍓
• --backtrace-format format — Specify the format of the backtrace written to the files specified by --backtrace-file, one of plain, xml or json. Pick your fighter ✨
• --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). So you just write the words, the program does the decorating. 🎀

• --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. Keep the lore, basically. 💜
• --comments-generate — Create a comment with summary data (the date of creation, name and version of the cptutils package) in the output file. Receipts, generated. 🧾
• -h, --help — Brief help.
• --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. (Mandatory, bestie, not a suggestion 😭)

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). Iconic symmetry. 🌈

• --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. Nothing. Nada. 💀

• -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.
• -R, --range min/max — The (z) range of the output, or the segments if the --segments switch is also given. This one is mandatory, so don't skip it. 💖
• -s, --segments — The min and max arguments of the --range switch are interpreted as the segment numbers (starting at one). Note: starting at one, not zero. 🫶
• -v, --verbose — Verbose operation. Tell me everything, I'm listening 👑
• -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. ⚠️

• -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. Lowkey just vibing. 🦋
• -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.

• -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. 🙈

---

🔥 EXAMPLES 🔥

Extract the table with z-range from 2.5 to 5:

cptclip -v -o new.cpt -R 2.5/5 old.cpt

Extract the table with the first 5 segments:

cptclip -v -s -o new.cpt -R 1/5 old.cpt

---

👑 AUTHOR 👑

J.J. Green — the mastermind, the moment, the main character energy. 💜

---

🌈 SEE ALSO 🌈

makecpt(1).

---

and that's the whole page, bestie — cptutils 1.82, 9 July 2024 🎀 that's the source, version and date, fr fr, no cap, go slay ✨💖🦋