GRADIENT-CONVERT(1)

📦 version 1.82, in fedora 43, fedora 44

💅 GRADIENT-CONVERT(1) — user commands, bestie edition 💅

okay so welcome to gradient-convert, the little wrapper script that is genuinely out here doing the most so you don't have to 🫶

✨ NAME ✨

gradient-convert — converts gradients between formats, no cap

🌸 SYNOPSIS 🌸

gradient-convert [-b rgb] [-B] [-c] [-f rgb] [-g geometry] [-G] [-h]
                 [-i format] [-n rgb] [-o format] [-p] [-T rgb] [-v]
                 [-V] [-z] [-4] [-5] [-6] infile outfile

🦋 DESCRIPTION 🦋

so gradient-convert converts gradients to other formats, periodt. it's a wrapper script — which means it makes a whole bunch of calls to the individual programs from the cptutils package, like it's the group chat coordinator of your conversion. for example, to convert a GMT colour palette (cpt) to a PNG image, the programs cptsvg and svgpng would get called in sequence to generate the file you asked for. iconic teamwork honestly 🔥

the formats of the mandatory infile and outfile arguments are figured out from the file extensions — or you can just say it explicitly with the -i and -o options. your call bestie 💖

👑 OPTIONS 👑

first thing first, queen: in everything below, all rgb specifications should be of the form red/green/blue where the colour components are integers in the range 0 to 255. that's the whole vibe.

  • -b, --background rgb — sets the background colour of cpt output. 💜
heads up though: this only modifies the "background" field in the output cpt file. it does not touch the transparency — for that, go look at the --transparency option. not the same thing, don't get it twisted 🙈
  • --backtrace-file path — tells it a file to write a formatted backtrace to. the file only gets created if there is a backtrace created, typically when an error occurs. so like, it's a file that only shows up when things go wrong 😭
  • --backtrace-format format — sets the format of the backtrace written to the files specified by --backtrace-file, one of plain, xml or json.
  • -B, --burst — some of the file formats cptutils handles may contain multiple gradients: the Photoshop (grd) and SVG formats for example. by default, the program extracts only the first gradient from such files. but when --burst is selected, all gradients get extracted. in that case the outfile argument must be a directory — and bestie, that directory should already exist, okay? ⭐
  • -c, --capabilities — prints the capabilities of the program to stdout. this data (in YAML format) may be used to autoconfigure other programs which wish to use this program. the format should be self-explanatory, iykyk.
  • -f, --foreground rgb — sets the foreground colour of cpt output. 🎀
  • -g, --geometry widthxheight — specifies the size of the PNG image or SVG preview in pixels.
  • -G, --graphviz — prints the conversion graph to stdout in the GraphViz dot format. see dot(1) for details on creating a plot of the graph from this output. very demure, very graph 🌈
  • -h, --help — brief help. a lil snack of information.
  • -i, --input-format format — specifies the format of the input file. run the program with the --help option for a list of supported formats.
  • -n, --nan rgb — sets the NaN (no data) colour of cpt output.
  • -o, --output-format format — specifies the format of the output file. run the program with the --help option for a list of supported formats.
  • -p, --preview — includes a preview in the SVG output. see also the --geometry option. 👀
  • -T, --transparency rgb — when converting to a format which does not support transparency, replaces the transparency with the specified rgb colour. the swap, basically 💅
  • -v, --verbose — verbose operation. it will tell you everything, and honestly? good for it.
  • -V, --version — version information.
  • -z, --zip — for input formats which may contain multiple gradients (grd, svg), --zip extracts all of the gradients and zips them up. so yeah, you can think of it as similar to the burst option (--burst). the zipfile to be created should be the final argument, and when unzipped it will create a directory (containing the converted gradients) with the same name as the file with the .zip extension removed. chef's kiss 🧚
  • -4, --gmt4 — uses 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. pick a lane bestie 😤

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). don't say we didn't warn you ✨

  • -5, --gmt5 — uses 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 🍓

convert a GMT colour palette to a 200×20 pixel PNG image:

gradient-convert -v -g 200x20 legend.cpt legend.png

convert all gradients in a Photoshop gradient to GMT cpt files in a zipfile:

gradient-convert -v -i grd -o cpt -z froob.grd froob.zip

💀 CAVEATS 💀

the component programs in the conversion will generally have a number of options available for modifying the conversion behaviour, but only the most-often used of these options can be passed to component programs from gradient-convert. so like, not everything gets an invite to the party, sorry 😭

also note that those options which are passed to component programs are not checked for relevance. converting a GMT cpt file to GIMP format while using the irrelevant --geometry option will not cause an error — it will simply be ignored. the option is just there, vibing, being ignored. it's giving main character who got cut from the final edit 🙈

🫶 AUTHOR 🫶

J.J. Green

and that's the whole page bestie, you ate that 💖 this was cptutils version 1.82, dated 9 July 2024 — so if you're reading this, slay, go convert some gradients, and remember: the vibe changes, the flags don't. periodt 🌟💅🎀

📦 where this page comes from