logo
  1. home
  2. code
  3. cptutils
  4. gradient-convert(1)
J. W. Goethe
Colours are the deeds of light; its deeds and sufferings: thus considered we may expect from them some explanation respecting light itself.
J. W. Goethe preface to The Theory of Colour, 1810

Name

gradient-convert — convert gradients between formats

Synopsis

gradient-convert [-b rgb] [-B ] [-c ] [-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

The gradient-convert program converts gradients to other formats. It is a wrapper script which make a number of calls the individual programs from the cptutils package so, for example, to convert a GMT colour palette (cpt) to a PNG image, the programs cptsvg and svgpng would be called in sequence to generate the required file.

The formats of the mandatory infile and outfile arguments are determined from the file extensions, or can be specified explicitly by the -i and -o options.

OPTIONS

In the following, all rgb specifications should be of the form red/green/blue where the colour components are integers in the range 0 to 255.

-b, --background rgb

Set the background colour of cpt output.

Note that this only modifies the "background" field in the output cpt file, it does not affect the transparency (see the --transparency option in that regard).

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

--backtrace-format format

Specify 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 handled by cptutils may contain multiple gradients: the Photoshop (grd) and SVG formats for example. By default, the program will extract only the first gradient from such files; but when the --burst option is selected then all gradients will be extracted. In this case the outfile argument must be a directory (and that directory should already exist).

-c, --capabilities

Print 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.

-C, --retain-comments

Use the comments in the input file as the comments for the output file.

This option will not error if comment retention is not possible (if one of the intermediate conversion targets does not support comments, for example).

-f, --foreground rgb

Set the foreground colour of cpt output.

-g, --geometry widthxheight

Specify the size of the PNG image or SVG preview in pixels.

-G, --graphviz

Print 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.

-h, --help

Brief help.

-i, --input-format format

Specify the format of the input file. Run the program with the --help option for a list of supported formats.

-n, --nan rgb

Set the NaN (no data) colour of cpt output.

-o, --output-format format

Specify the format of the output file. Run the program with the --help option for a list of supported formats.

-p, --preview

Include a preview in the SVG output. See also the --geometry option.

-T, --transparency rgb

When converting to a format which does not support transparency, replace the transparency with the specified rgb colour.

-v, --verbose

Verbose operation.

-V, --version

Version information.

-z, --zip

For input formats which may contain multiple gradients (grd, svg) the --zip extracts all of the gradients and zips them up. Thus it can be viewed 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.

-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).

-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

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.

Note also that those options which are passed to component programs are not checked for relevance. Converting a GMT cpt file to GIMP format while using using the irrelevant --geometry option will not cause an error, it will simply be ignored.

AUTHOR

J.J. Green