Cpt format documentation

I currently maintain a relatively simple Matlab function, cptcmap.m, that parses v4 color palette tables and mimics them with a Matlab colormap. I wrote it almost a decade ago, and it’s long overdue for an update to support the v5 format, and to support options like color names that were left out of my earlier version but seem to be more widely-used in the current default set of color palettes.

However, I haven’t yet found a full description of the new file format. I’ve been mostly parsing it from the various usage docs, and will hopefully be able to reconstruct the rest by studying the gmtlib_read_cpt function from the source code. But perhaps some of the experts could point me to a better resource?

In particular, I’m curious if the current version of GMT is back-compatible with the older v4 format, even though it emphasizes the new v5 format in all its docs. (If so, it should be a little easier to mirror the internal GMT cpt-parsing code, I think).

Kelly, see https://docs.generic-mapping-tools.org/dev/reference/features.html#color-palette-tables

I think the biggest change, conceptually, is the switch from per-file colour model to per-segment. Previously


indicate that the colour triples were H S V values, now this is given by the form of the colour, so R/G/B, H-S-V or C/Y/M/K. Since the form of the colour determines its model, one might think COLOR_MODEL is redundant, but it can also indicate the interpolation model eg


says the colour model is HSV (redundant) and interpolate in HSV too. So GMT 5+ makes aliases for +RGB, +HSV, +CMYK, namely rgb, hsv, cmyk. Note that RGB is the default so rgb is redundant too. The old names are still accepted for backwards compatibility.

Incidentally, there’s another C parser for cpt 4/5 here which might be useful.

Thank you both for the pointers! And thank you jjg for clarifying the per-file vs. per-segment change (I hadn’t picked up on that subtlety) and for linking to your parser. I’ll likely rely on that quite a bit when rewriting my version.

I could alternatively add a mex file wrapper to the cptutils package, and use it directly to parse the files, but I find Matlab users tend to shy away from using mex-ed code unless it provides a serious speed benefit. So I’ll see where I can get with a pure Matlab parser first.

I’d actually recommend a Matalb-only parser, MEX is not too bad but has OS specific issues, worth the pain if the code is performance critical, but parsing cpts isn’t, they’re tiny and the format is not that complicated.