src/tiff/man/tiffcp.1

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