CPTCAT(1)

✨ NAME ✨

okay so cptcat — it concatenates GMT colour palette tables (you know, cpt files) 💅 that's it, that's the whole job, and it does it beautifully

it's the cptcat(1) user command, btw, living in section 1 of the manual, we love a user command era 🫶

---

🌸 SYNOPSIS 🌸

cptcat [-h] [-H] [-m model] [-o path] [-S] [-v] [-V] [-z] [-Z] [-4] [-5]
       [-6] path...

---

💖 DESCRIPTION 💖

so the cptcat utility concatenates GMT colour palette table (cpt) files. iconic behaviour, no notes ✨

the mandatory path argument(s) are your input files, and bestie, you can put them in any order you want. BUT — and this is the part that matters — when they're sorted, the maximum (z-value) of the lower file should equal the minimum of the upper file. if your files aren't in that form yet, you can glow them up with the makecpt(1) utility first 💅

the background colour gets taken from the lower (or lowest) file, and the foreground comes from the upper one. cute, right? 🎀

and if you don't specify the -o option, the program just writes to stdout. simple. clean. slay.

---

👑 OPTIONS 👑

• --backtrace-file path — tell it a file to write a formatted backtrace to. heads up: the file only gets created if there's actually a backtrace to write, which typically happens when an error occurs 😭 so like, don't expect an empty file just vibing there
• --backtrace-format format — pick the format of the backtrace that goes to the files from --backtrace-file. your options are plain, xml or json. choose your fighter 💀
• --comments-read path — read the comments from the specified path and add them to the output gradient. the format is just a plain text multi-line document, no comment delimiters needed — the program adds those itself, she's got it 🫶
• --comments-write path — write the comments that were in the input out to the specified path
• --comments-retain — use the comments from the input file as the comments for the output file. recycling! sustainable queen 🌸
• --comments-generate — create a comment with summary data in the output file: the date of creation, plus the name and version of the cptutils package. receipts, basically 🧾
• -h, --help — brief help. short and sweet, we love her
• -H, --hinge-hard — adds a HARD_HINGE to the output, see HINGES below 👇
• -S, --hinge-soft — adds a SOFT_HINGE to the output, see HINGES below 👇
• -m, --model model — when writing the output, convert all colours to the specified model, one of "rgb" or "hsv". this has no effect on non-colour segments, so don't come for her about those 💅
• -o, --output path — write the output to path instead of stdout. main character move, honestly
• -v, --verbose — verbose operation. she will tell you things 🔥
• -V, --version — version information ✨
• -z, --z-normalise — normalise the z-values in the cpt output into the range 0/1 (or into -1/1 if a hinge is present), and add a RANGE directive if it isn't already present in the input. this is the form used in GMT master files 👑

this option requires that the output cpt version is at least 5. no 5, no z-normalise, sorry bestie 😭

• -Z, --z-denormalise — set the z-values in the cpt output into the range given by the RANGE directive, and then remove that directive. if there's no RANGE then this option does literally nothing. she's just standing there. existing. 💀
• -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 please specify this option if your use of the output depends on the GMT 4 layout — say, because it's being consumed by a custom parser 👀

• -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 and CMYK, and by a dash for HSV.

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

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

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

---

🦋 HINGES 🦋

okay so this is the part where cptcat is built different from the other programs that read and write the cpt format. those ones retain the hinge (if any) they find in the input. this one? she does her own thing 💅

the reasoning: an expected use-case for this program is combining bathymetry and topography schemes. those typically would not have hinges, and the result is a bathymetry-topography scheme, which typically would. so like, the whole point is making one where there wasn't one 🌊⛰️

so here's the tea:

• any hinges in the input will be ignored (and a warning will be issued when that happens — she's not being sneaky about it)
• the output will have a hinge only if one of the --hinge-hard (-H) or --hinge-soft (-S) options is given

these are a recent GMT feature, so the --gmt6 option is required if you want a hinge. periodt ✨

---

🌈 EXAMPLES 🌈

want to create a cpt-file topobath.cpt from topo.cpt and bath.cpt, adding a hard hinge and normalising the output — you know, the typical form of a "dynamic" or "master" cpt file? say less 🫶

cptcat -v -H -6 -z -o topobath.cpt topo.cpt bath.cpt

---

💜 AUTHOR 💜

J.J. Green — the icon, the legend, the moment 👑

---

⭐ SEE ALSO ⭐

makecpt(1) — your other bestie, go say hi 🎀

---

okay that's the whole page, bestie 💖 this one's from cptutils 1.82, dated 9 July 2024 — so you know the info is fresh, no cap. go forth and concatenate those palettes, you absolute legend 🌸✨💅