NAME
xcf2pnm - convert from GIMP xcf files to ppm/pgm/pbm format
SYNOPSIS
xcf2pnm [ options ] filename [ layer names ]
DESCRIPTION
xcf2pnm is a command-line tool that converts image files in the XCF
format used by gimp(1) to the generic image formats pbm(5), pgm(5), and
ppm(5), flattening layers if necessary. It does not need to have the
Gimp engine itself available.
GENERAL OPTIONS
-a filename, --alpha filename
Output a transparency mask for the flattened image to filename
as a pgm(5) file, in addition to the ordinary output. If the
flattened image is completely opaque, this will produce an
error message and exit status 101; use -A to suppress this.
-A, --force-alpha
Invent a trivial alpha channel even if the flattened image is
completely opaque.
-b color, --background color
Use this color for transparent pixels in the image. The color
can be given as #rrggbb or #rgb hexadecimal values, or as an
X11 color name (which will only work if a color name database
can be found in one of a number of standard locations).
-c, --color, --colour
Force the output to use RGB color space even if it there are
more compact alternatives. This will be selected automatically
if the output file’s name ends with .ppm.
-C, --autocrop
Set the converted part of the image such that it just include
the boundaries of the visible (or selected) layers. This may
make it either smaller or larger than the canvas, depending on
the position and size of the visible layers. (Note that the
contents of the layers is not taken into account when
autocropping).
In the absence of options that specify otherwise, the converted
image will cover the entire XCF canvas.
-D, --dissolve
Do a "dissolve" step to eliminate partial transparency after
flattening. If -b is also given, this happens before the
background color is applied.
-f, --full-image
First flatten the entire image to a memory buffer before
writing output. Then analyse the image to decide on the details
of the output format (e.g., whether a grayscale output is
sufficient). Without this option, the program flattens only a
singe row of "tiles" (height 64) at a time.
-g, --gray, --grey
Force the output to be a grayscale image even if it may be
monochrome. If any colored pixels are encountered, exit with
status 103. This will be selected automatically if the output
file’s name ends with .pgm.
-G, --for-gif
Assert that the flattened image will have no partial
transparency (allowing a more compact representation of the
alpha output). Exit with status 102 if the flattened image has
any partial transparency. If -b is also given, this tests
whether there there is partial transparency before applying the
background color.
-h, --help
Print an option summery to standard output and exit with a
return code of 0.
-j, --bzip
Equivalent to -Z bzcat. Default if the filename ends with bz2.
-m, --mono
Force the output to be a monochrome image. If any colors
except black and white are encountered, exit with status 103.
This will be selected automatically if the output file’s name
ends with .pbm.
-n, --pnm
Suppress the automatic choice of -c, -g, or -m based on output
filename, and instead select the output format based on image
contents. This is the default if the filename is not
recognized, and when writing to stdout.
-o filename, --output filename
Write the converted picture to filename instead of to standard
output.
-O x,y, --offset x,y
Offset the converted part of the image from the top-left corner
of the XCF canvas. Usually used with -S.
-S wxh, --size wxh
Crop the converted image to width w and height h.
-T, --truecolor
Use standard RGB compositing for flattening indexed layers.
Without this option, xcf2pnm will mimic the Gimp’s current
strategy of rounding each alpha value to either full
transparency or full opacity, and interpret all layer modes as
Normal.
-u, --utf8
Use the raw UTF-8 representation from the XCF file to compare
and display layer names. Ordinarily, layer names will be
converted to the character set of the current locale.
-v, --verbose
Print progress messages about the conversion to standard error.
-V, --version
Print the version numer of xcftools to standard output and exit
with a return code of 0.
-z, --gzip
Equivalent to -Z zcat. Default if the filename ends with gz.
-Z command, --unpack command
Specify a command that the input file is filtered through
before being interpreted as an XCF file. The command is invoked
as command filename and must produce output to its standard
output. Note that it is not possible to specify arguments as
part of command. An uncompressor is selected automatically if
the filename ends with gz or bz2; to suppress this, use -Z cat
(which is implemented without actually starting a cat(1)
process).
Several groups of options are mutually incompatible; in each group the
one given last will win:
1) -A and -b.
2) -c, -g, -m, and -n.
3) -D and -G.
4) -j, -z, and -Z.
5) -C and -O/-S.
LAYER SPECIFICATIONS
If no layer name is given on the command line, all of the visible
layers in the XCF file are merged to produce the output image. It is
also possible to specify the layers to merge explicitly, by giving
their names as separate arguments after the input filename. In that
case, the output will contain only the named layers. The layers will be
merged in the order they appear on the command line, with the leftmost
being "at the bottom" - that is, the layer ordering in the XCF file
will be ignored.
The following options can be given after a layer name to override the
global properties of the layer:
--mask Enable the layer mask.
--mode mode
Set the layer mode (e.g., Normal or Multiply).
--nomask
Disable the layer mask.
--opacity n
Set the opacity on a scale from 0 to 255 (as used internally)
--percent n
Set the opacity on a scale from 0 to 100 (as in the Gimp user
interface).
EXIT STATUS
The exit status of xcf2pnm is
0 Success
20 Problems parsing the command line, including unknown color names
(or missing color name directory) for -b.
21 The specified XCF file does not exist or cannot be read.
22 A layer named on the command line was not found, or the --mask
option was used for a layer that has no layer mask.
100 Transparent pixels were found, but neither -a nor -b was given.
101 The -a option was given yet the image has no transparency. (Use
-A to go on anyway).
102 The -G option was given, yet partial transparency was found.
103 -g (or -m) was given, yet colored (or gray) pixels were found.
123 The XCF file contains presumably valid features that xcftools does
not support. (As of this writing there is no known way of getting
the Gimp to write an XCF file that will provoke this return.
Please notify the author if you discover one).
125 The XCF file is malformed.
126 An uncompression program could not be executed, or terminated
abnormally.
127 Unexpected I/O error, internal errors, or other "this can’t
happen" situations.
If an uncompression program returns an error exit status, this will be
returned from xcf2pnm too.
EXAMPLES
xcf2pnm -b white foo.xcf > foo.ppm
xcf2pnm -a footrans.pgm -o foo.ppm foo.xcf Layer1 Layer2
To test whether the flattened image has any transparency, use
xcf2pnm foo.xcf > /dev/null
To test whether the flattened image has partially transparent pixels,
use
xcf2pnm -b white -G > /dev/null
BUGS AND LIMITATIONS
When several partially transparent layers are merged, the pixel values
are interpolated without gamma correction. (The Gimp also does it this
way). Some slight rounding errors in the interpolation are inevitable;
xcf2pnm sometimes has different rounding errors than the Gimp itself,
especially when more than two layers are involved, or in case of some
of the more exotic layer modes. These differences are usually not
visible to the eye.
Floating selections are currently not handled correctly.
There are probably other bugs lurking in corner cases. If you discover
one, please notify the author.
FILES
/etc/X11/rgb.txt
/usr/share/X11/rgb.txt
/usr/lib/X11/rgb.txt
Color name database for -b.
AUTHOR
xcf2pnm was written by Henning Makholm <henning@makholm.net>.
SEE ALSO
xcfinfo(1), xcf2png(1)