man/tiffcp.1

   1 .\" $Id: tiffcp.1,v 1.9.2.1 2010-06-04 16:51:14 fwarmerdam 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 jpeg
  87 for baseline JPEG compression,
  88 .B zip
  89 for Deflate compression,
  90 .B g3
  91 for CCITT Group 3 (T.4) compression,
  92 and
  93 .B g4
  94 for CCITT Group 4 (T.6) compression.
  95 By default
  96 .I tiffcp
  97 will compress data according to the value of the
  98 .I Compression
  99 tag found in the source file.
 100 .IP
 101 The
 102 .SM CCITT
 103 Group 3 and Group 4 compression algorithms can only
 104 be used with bilevel data.
 105 .IP
 106 Group 3 compression can be specified together with several
 107 T.4-specific options:
 108 .B 1d
 109 for 1-dimensional encoding,
 110 .B 2d
 111 for 2-dimensional encoding,
 112 and
 113 .B fill
 114 to force each encoded scanline to be zero-filled so that the
 115 terminating EOL code lies on a byte boundary.
 116 Group 3-specific options are specified by appending a ``:''-separated
 117 list to the ``g3'' option; e.g.
 118 .B "\-c g3:2d:fill"
 119 to get 2D-encoded data with byte-aligned EOL codes.
 120 .IP
 121 .SM LZW
 122 compression can be specified together with a
 123 .I predictor
 124 value.
 125 A predictor value of 2 causes
 126 each scanline of the output image to undergo horizontal
 127 differencing before it is encoded; a value
 128 of 1 forces each scanline to be encoded without differencing.
 129 LZW-specific options are specified by appending a ``:''-separated
 130 list to the ``lzw'' option; e.g.
 131 .B "\-c lzw:2"
 132 for
 133 .SM LZW
 134 compression with horizontal differencing.
 135 .TP
 136 .B \-f
 137 Specify the bit fill order to use in writing output data.
 138 By default,
 139 .I tiffcp
 140 will create a new file with the same fill order as the original.
 141 Specifying
 142 .B "\-f lsb2msb"
 143 will force data to be written with the FillOrder tag set to
 144 .SM LSB2MSB,
 145 while
 146 .B "\-f msb2lsb"
 147 will force data to be written with the FillOrder tag set to
 148 .SM MSB2LSB.
 149 .TP
 150 .B \-i
 151 Ignore non-fatal read errors and continue processing of the input file.
 152 .TP
 153 .B \-l
 154 Specify the length of a tile (in pixels).
 155 .I tiffcp
 156 attempts to set the tile dimensions so
 157 that no more than 8 kilobytes of data appear in a tile.
 158 .TP
 159 .B \-L
 160 Force output to be written with Little-Endian byte order.
 161 This option only has an effect when the output file is created or
 162 overwritten and not when it is appended to.
 163 .TP
 164 .B \-M
 165 Suppress the use of memory-mapped files when reading images.
 166 .TP
 167 .B \-p
 168 Specify the planar configuration to use in writing image data
 169 that has one 8-bit sample per pixel.
 170 By default,
 171 .I tiffcp
 172 will create a new file with the same planar configuration as
 173 the original.
 174 Specifying
 175 .B "\-p contig"
 176 will force data to be written with multi-sample data packed
 177 together, while
 178 .B "\-p separate"
 179 will force samples to be written in separate planes.
 180 .TP
 181 .B \-r
 182 Specify the number of rows (scanlines) in each strip of data
 183 written to the output file.
 184 By default (or when value
 185 .B 0
 186 is specified),
 187 .I tiffcp
 188 attempts to set the rows/strip
 189 that no more than 8 kilobytes of data appear in a strip. If you specify
 190 special value
 191 .B \-1
 192 it will results in infinite number of the rows per strip. The entire image
 193 will be the one strip in that case.
 194 .TP
 195 .B \-s
 196 Force the output file to be written with data organized in strips
 197 (rather than tiles).
 198 .TP
 199 .B \-t
 200 Force the output file to be written with data organized in tiles (rather than
 201 strips). options can be used to force the resultant image to be written as
 202 strips or tiles of data, respectively.
 203 .TP
 204 .B \-w
 205 Specify the width of a tile (in pixels).
 206 .I tiffcp
 207 attempts to set the tile dimensions so that no more than 8 kilobytes of data
 208 appear in a tile.
 209 .I tiffcp
 210 attempts to set the tile dimensions so that no more than 8 kilobytes of data
 211 appear in a tile.
 212 .TP
 213 .B \-x
 214 Force the output file to be written with PAGENUMBER value in sequence.
 215 .TP
 216 .BI \-,= character
 217 substitute
 218 .I character
 219 for `,' in parsing image directory indices
 220 in files.  This is necessary if filenames contain commas.
 221 Note that
 222 .B \-,=
 223 with whitespace immediately following will disable
 224 the special meaning of the `,' entirely.  See examples.
 225 .SH EXAMPLES
 226 The following concatenates two files and writes the result using
 227 .SM LZW
 228 encoding:
 229 .RS
 230 .nf
 231 tiffcp \-c lzw a.tif b.tif result.tif
 232 .fi
 233 .RE
 234 .PP
 235 To convert a G3 1d-encoded
 236 .SM TIFF
 237 to a single strip of G4-encoded data the following might be used:
 238 .RS
 239 .nf
 240 tiffcp \-c g4 \-r 10000 g3.tif g4.tif
 241 .fi
 242 .RE
 243 (1000 is just a number that is larger than the number of rows in
 244 the source file.)
 245
 246 To extract a selected set of images from a multi-image TIFF file, the file
 247 name may be immediately followed by a `,' separated list of image directory
 248 indices.  The first image is always in directory 0.  Thus, to copy the 1st and
 249 3rd images of image file ``album.tif'' to ``result.tif'':
 250 .RS
 251 .nf
 252 tiffcp album.tif,0,2 result.tif
 253 .fi
 254 .RE
 255
 256 A trailing comma denotes remaining images in sequence.  The following command
 257 will copy all image with except the first one:
 258 .RS
 259 .nf
 260 tiffcp album.tif,1, result.tif
 261 .fi
 262 .RE
 263
 264 Given file ``CCD.tif'' whose first image is a noise bias
 265 followed by images which include that bias,
 266 subtract the noise from all those images following it
 267 (while decompressing) with the command:
 268 .RS
 269 .nf
 270 tiffcp \-c none \-b CCD.tif CCD.tif,1, result.tif
 271 .fi
 272 .RE
 273
 274 If the file above were named ``CCD,X.tif'', the
 275 .B \-,=
 276 option would
 277 be required to correctly parse this filename with image numbers,
 278 as follows:
 279 .RS
 280 .nf
 281 tiffcp \-c none \-,=% \-b CCD,X.tif CCD,X%1%.tif result.tif
 282 .SH "SEE ALSO"
 283 .BR pal2rgb (1),
 284 .BR tiffinfo (1),
 285 .BR tiffcmp (1),
 286 .BR tiffmedian (1),
 287 .BR tiffsplit (1),
 288 .BR libtiff (3TIFF)
 289 .PP
 290 Libtiff library home page:
 291 .BR http://www.remotesensing.org/libtiff/