NAME

cptcat - concatenate GMT colour palette tables.

SYNOPSIS

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

DESCRIPTION

The cptcat utility concatenates GMT colour palette table (cpt) files. The mandatory path argument(s) specify the input files which may be specified in any order. However, when sorted, the maximum (z-value) of the lower file should equal the minimum of the upper file; files can be modified with the makecpt(1) utility to be in this form.

The background colour will be taken from that of the lower (or lowest) file, and the foreground from that of the upper (notwithstanding the --background and --foreground options).

The program will write to stdout if the -o option is not specified.

OPTIONS

-b, --background rgb, --no-background

Set or remove the background colour of the output.

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

--comments-read path

Read the comments from the specified path and add them to the output gradient.

The format is custom XML which should be fairly easy to generate, see the output of --comments-write for examples.

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

--comments-generate

Create a comment with summary data (the date of creation, name and version of the cptutils package) in the output file.

-f, --foreground rgb, --no-foreground

Set or remove the foreground colour of the output.

-h, --help

Brief help.

-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

On writing the output, convert all colours to the specified model, one of "rgb" or "hsv". This has no effect on non-colour segments.

-n, --nan rgb, --no-nan

Set or remove the NaN (no data) colour of the output.

-o, --output path

Write the output to path, rather than stdout.

-v, --verbose

Verbose operation.

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

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

HINGES

The treatment of hinges in this program is rather different to that of the other programs reading and writing the cpt format, those retain the hinge (if any) found in the input.

However, an expected use-case for this program is to combine bathymetry and topography schemes, which would typically not have hinges, producing a bathymetry-topography scheme, which typically would.

Hence any hinges in the input will be ignored (a warning will be issued in this case), and the output will have a hinge only if one of the --hinge-hard (-H) or --hinge-soft (-S) options are given. These are a recent GMT feature, so the --gmt6 option is required.

EXAMPLES

Create a cpt-file topobath.cpt from topo.cpt and bath.cpt, adding a hard hinge and normalising the output (the typical form of a "dynamic" or "master" cpt file)

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

AUTHOR

J.J. Green