NAME

cptclip - extract a sub-table from a GMT colour palette table (cpt).

SYNOPSIS

cptclip -R min/max [-b rgb] [-f rgb] [-h] [-m model] [-n rgb] [-o path] [-s] [-v] [-V] [-z] [-Z] [-4] [-5] [-6] [path]

DESCRIPTION

The cptclip utility extracts a sub-table from a cpt format file. The arguments to the mandatory --range option, min/max, are interpreted as the (z) limits of the output unless the --segments switch is specified, in which case they are the segment numbers.

If the input has a hinge and the selected clipping range does not include that hinge, then it will be removed in the output.

The program will read from stdin if a file is not specified as the final argument, and write to stdout if the --output option is not specified.

Note that some of the functionality of this program is included in recent versions of the GMT program makecpt(1).

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.

--hinge value

Specify the z-value of the hinge in the cpt file. If there is no hinge directive (i.e., a SOFT_HINGE or HARD_HINGE) in the input, then this option has no effect.

When normalising (with the --z-normalise option), this gives the z-value in the input which is mapped to zero. That z-value must be one of the stops in the input.

When denormalising (with the --z-denormalise option), this gives the value in the output to which zero in the input is mapped. This option can be viewed as the counterpart to the +hvalue appended to the -C option for the makecpt(1).

--hinge-active

If the input cpt has a SOFT_HINGE directive, then activate that hinge (resulting in independent scaling of the two halves of the gradient either side of the hinge).

If the input does not have such a directive, then this option has no effect.

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

-R, --range min/max

The (z) range of the output, or the segments if the --segments switch is also given.

-s, --segments

The min and max arguments of the --range switch are interpreted as the segment numbers (starting at one).

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

EXAMPLES

Extract the table with z-range from 2.5 to 5:

cptclip -v -o new.cpt -R 2.5/5 old.cpt

Extract the table with the first 5 segments:

cptclip -v -s -o new.cpt -R 1/5 old.cpt

AUTHOR