src/tiff/man/tiffcp.1

   1 .\"
   2 .\" Copyright (c) 1988-1997 Sam Leffler
   3 .\" Copyright (c) 1991-1997 Silicon Graphics, Inc.
   4 .\"
   5 .\" Permission to use, copy, modify, distribute, and sell this software and
   6 .\" its documentation for any purpose is hereby granted without fee, provided
   7 .\" that (i) the above copyright notices and this permission notice appear in
   8 .\" all copies of the software and related documentation, and (ii) the names of
   9 .\" Sam Leffler and Silicon Graphics may not be used in any advertising or
  10 .\" publicity relating to the software without the specific, prior written
  11 .\" permission of Sam Leffler and Silicon Graphics.
  12 .\"
  13 .\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
  14 .\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
  15 .\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  16 .\"
  17 .\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
  18 .\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
  19 .\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
  20 .\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
  21 .\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  22 .\" OF THIS SOFTWARE.
  23 .\"
  24 .if n .po 0
  25 .TH TIFFCP 1 "February 24, 2007" "libtiff"
  26 .SH NAME
  27 tiffcp \- copy (and possibly convert) a
  28 .SM TIFF
  29 file
  30 .SH SYNOPSIS
  31 .B tiffcp
  32 [
  33 .I options
  34 ]
  35 .I "src1.tif ... srcN.tif dst.tif"
  36 .SH DESCRIPTION
  37 .I tiffcp
  38 combines one or more files created according
  39 to the Tag Image File Format, Revision 6.0
  40 into a single
  41 .SM TIFF
  42 file.
  43 Because the output file may be compressed using a different
  44 algorithm than the input files,
  45 .I tiffcp
  46 is most often used to convert between different compression
  47 schemes.
  48 .PP
  49 By default,
  50 .I tiffcp
  51 will copy all the understood tags in a
  52 .SM TIFF
  53 directory of an input
  54 file to the associated directory in the output file.
  55 .PP
  56 .I tiffcp
  57 can be used to reorganize the storage characteristics of data
  58 in a file, but it is explicitly intended to not alter or convert
  59 the image data content in any way.
  60 .SH OPTIONS
  61 .TP
  62 .BI \-b " image"
  63 subtract the following monochrome image from all others
  64 processed.  This can be used to remove a noise bias
  65 from a set of images.  This bias image is typically an
  66 image of noise the camera saw with its shutter closed.
  67 .TP
  68 .B \-B
  69 Force output to be written with Big-Endian byte order.
  70 This option only has an effect when the output file is created or
  71 overwritten and not when it is appended to.
  72 .TP
  73 .B \-C
  74 Suppress the use of ``strip chopping'' when reading images
  75 that have a single strip/tile of uncompressed data.
  76 .TP
  77 .B \-c
  78 Specify the compression to use for data written to the output file:
  79 .B none
  80 for no compression,
  81 .B packbits
  82 for PackBits compression,
  83 .B lzw
  84 for Lempel-Ziv & Welch compression,
  85 .B zip
  86 for Deflate compression,
  87 .B lzma
  88 for LZMA2 compression,
  89 .B jpeg
  90 for baseline JPEG compression,
  91 .B g3
  92 for CCITT Group 3 (T.4) compression,
  93 and
  94 .B g4
  95 for CCITT Group 4 (T.6) compression.
  96 By default
  97 .I tiffcp
  98 will compress data according to the value of the
  99 .I Compression
 100 tag found in the source file.
 101 .IP
 102 The
 103 .SM CCITT
 104 Group 3 and Group 4 compression algorithms can only
 105 be used with bilevel data.
 106 .IP
 107 Group 3 compression can be specified together with several
 108 T.4-specific options:
 109 .B 1d
 110 for 1-dimensional encoding,
 111 .B 2d
 112 for 2-dimensional encoding,
 113 and
 114 .B fill
 115 to force each encoded scanline to be zero-filled so that the
 116 terminating EOL code lies on a byte boundary.
 117 Group 3-specific options are specified by appending a ``:''-separated
 118 list to the ``g3'' option; e.g.
 119 .B "\-c g3:2d:fill"
 120 to get 2D-encoded data with byte-aligned EOL codes.
 121 .IP
 122 .SM LZW, Deflate
 123 and
 124 .SM LZMA2
 125 compression can be specified together with a
 126 .I predictor
 127 value. A predictor value of 2 causes each scanline of the output image to
 128 undergo horizontal differencing before it is encoded; a value of 1 forces each
 129 scanline to be encoded without differencing. A value 3 is for floating point
 130 predictor which you can use if the encoded data are in floating point format.
 131 LZW-specific options are specified by appending a ``:''-separated list to the
 132 ``lzw'' option; e.g.
 133 .B "\-c lzw:2"
 134 for
 135 .SM LZW
 136 compression with horizontal differencing.
 137 .IP
 138 .SM Deflate
 139 and
 140 .SM LZMA2
 141 encoders support various compression levels (or encoder presets) set as
 142 character ``p'' and a preset number. ``p1'' is the fastest one with the worst
 143 compression ratio and ``p9'' is the slowest but with the best possible ratio;
 144 e.g.
 145 .B "\-c zip:3:p9"
 146 for
 147 .SM Deflate
 148 encoding with maximum compression level and floating point predictor.
 149 .TP
 150 .B \-f
 151 Specify the bit fill order to use in writing output data.
 152 By default,
 153 .I tiffcp
 154 will create a new file with the same fill order as the original.
 155 Specifying
 156 .B "\-f lsb2msb"
 157 will force data to be written with the FillOrder tag set to
 158 .SM LSB2MSB,
 159 while
 160 .B "\-f msb2lsb"
 161 will force data to be written with the FillOrder tag set to
 162 .SM MSB2LSB.
 163 .TP
 164 .B \-i
 165 Ignore non-fatal read errors and continue processing of the input file.
 166 .TP
 167 .B \-l
 168 Specify the length of a tile (in pixels).
 169 .I tiffcp
 170 attempts to set the tile dimensions so
 171 that no more than 8 kilobytes of data appear in a tile.
 172 .TP
 173 .B \-L
 174 Force output to be written with Little-Endian byte order.
 175 This option only has an effect when the output file is created or
 176 overwritten and not when it is appended to.
 177 .TP
 178 .B \-M
 179 Suppress the use of memory-mapped files when reading images.
 180 .TP
 181 .B \-p
 182 Specify the planar configuration to use in writing image data
 183 that has one 8-bit sample per pixel.
 184 By default,
 185 .I tiffcp
 186 will create a new file with the same planar configuration as
 187 the original.
 188 Specifying
 189 .B "\-p contig"
 190 will force data to be written with multi-sample data packed
 191 together, while
 192 .B "\-p separate"
 193 will force samples to be written in separate planes.
 194 .TP
 195 .B \-r
 196 Specify the number of rows (scanlines) in each strip of data
 197 written to the output file.
 198 By default (or when value
 199 .B 0
 200 is specified),
 201 .I tiffcp
 202 attempts to set the rows/strip
 203 that no more than 8 kilobytes of data appear in a strip. If you specify
 204 special value
 205 .B \-1
 206 it will results in infinite number of the rows per strip. The entire image
 207 will be the one strip in that case.
 208 .TP
 209 .B \-s
 210 Force the output file to be written with data organized in strips
 211 (rather than tiles).
 212 .TP
 213 .B \-t
 214 Force the output file to be written with data organized in tiles (rather than
 215 strips). options can be used to force the resultant image to be written as
 216 strips or tiles of data, respectively.
 217 .TP
 218 .B \-w
 219 Specify the width of a tile (in pixels).
 220 .I tiffcp
 221 attempts to set the tile dimensions so that no more than 8 kilobytes of data
 222 appear in a tile.
 223 .I tiffcp
 224 attempts to set the tile dimensions so that no more than 8 kilobytes of data
 225 appear in a tile.
 226 .TP
 227 .B \-x
 228 Force the output file to be written with PAGENUMBER value in sequence.
 229 .TP
 230 .BI \-,= character
 231 substitute
 232 .I character
 233 for `,' in parsing image directory indices
 234 in files.  This is necessary if filenames contain commas.
 235 Note that
 236 .B \-,=
 237 with whitespace immediately following will disable
 238 the special meaning of the `,' entirely.  See examples.
 239 .SH EXAMPLES
 240 The following concatenates two files and writes the result using
 241 .SM LZW
 242 encoding:
 243 .RS
 244 .nf
 245 tiffcp \-c lzw a.tif b.tif result.tif
 246 .fi
 247 .RE
 248 .PP
 249 To convert a G3 1d-encoded
 250 .SM TIFF
 251 to a single strip of G4-encoded data the following might be used:
 252 .RS
 253 .nf
 254 tiffcp \-c g4 \-r 10000 g3.tif g4.tif
 255 .fi
 256 .RE
 257 (1000 is just a number that is larger than the number of rows in
 258 the source file.)
 259
 260 To extract a selected set of images from a multi-image TIFF file, the file
 261 name may be immediately followed by a `,' separated list of image directory
 262 indices.  The first image is always in directory 0.  Thus, to copy the 1st and
 263 3rd images of image file ``album.tif'' to ``result.tif'':
 264 .RS
 265 .nf
 266 tiffcp album.tif,0,2 result.tif
 267 .fi
 268 .RE
 269
 270 A trailing comma denotes remaining images in sequence.  The following command
 271 will copy all image with except the first one:
 272 .RS
 273 .nf
 274 tiffcp album.tif,1, result.tif
 275 .fi
 276 .RE
 277
 278 Given file ``CCD.tif'' whose first image is a noise bias
 279 followed by images which include that bias,
 280 subtract the noise from all those images following it
 281 (while decompressing) with the command:
 282 .RS
 283 .nf
 284 tiffcp \-c none \-b CCD.tif CCD.tif,1, result.tif
 285 .fi
 286 .RE
 287
 288 If the file above were named ``CCD,X.tif'', the
 289 .B \-,=
 290 option would
 291 be required to correctly parse this filename with image numbers,
 292 as follows:
 293 .RS
 294 .nf
 295 tiffcp \-c none \-,=% \-b CCD,X.tif CCD,X%1%.tif result.tif
 296 .SH "SEE ALSO"
 297 .BR pal2rgb (1),
 298 .BR tiffinfo (1),
 299 .BR tiffcmp (1),
 300 .BR tiffmedian (1),
 301 .BR tiffsplit (1),
 302 .BR libtiff (3TIFF)
 303 .PP
 304 Libtiff library home page:
 305 .BR http://www.remotesensing.org/libtiff/