src/tiff/man/tiffcp.1

   1 .\" $Id: tiffcp.1,v 1.6 2005/11/02 11:07:19 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 "September 20, 2005" "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 .B \-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 \-l
 151 Specify the length of a tile (in pixels).
 152 .I tiffcp
 153 attempts to set the tile dimensions so
 154 that no more than 8 kilobytes of data appear in a tile.
 155 .TP
 156 .B \-L
 157 Force output to be written with Little-Endian byte order.
 158 This option only has an effect when the output file is created or
 159 overwritten and not when it is appended to.
 160 .TP
 161 .B \-M
 162 Suppress the use of memory-mapped files when reading images.
 163 .TP
 164 .B \-p
 165 Specify the planar configuration to use in writing image data
 166 that has one 8-bit sample per pixel.
 167 By default,
 168 .I tiffcp
 169 will create a new file with the same planar configuration as
 170 the original.
 171 Specifying
 172 .B "\-p contig"
 173 will force data to be written with multi-sample data packed
 174 together, while
 175 .B "\-p separate"
 176 will force samples to be written in separate planes.
 177 .TP
 178 .B \-r
 179 Specify the number of rows (scanlines) in each strip of data
 180 written to the output file.
 181 By default (or when value
 182 .B 0
 183 is specified),
 184 .I tiffcp
 185 attempts to set the rows/strip
 186 that no more than 8 kilobytes of data appear in a strip. If you specify
 187 special value
 188 .B -1
 189 it will results in infinite number of the rows per strip. The entire image
 190 will be the one strip in that case.
 191 .TP
 192 .B \-s
 193 Force the output file to be written with data organized in strips
 194 (rather than tiles).
 195 .TP
 196 .B \-t
 197 Force the output file to be written with data organized in tiles
 198 (rather than strips).
 199 options can be used to force the resultant image to be written
 200 as strips or tiles of data, respectively.
 201 .TP
 202 .B \-w
 203 Specify the width of a tile (in pixels).
 204 .I tiffcp
 205 attempts to set the tile dimensions so
 206 that no more than 8 kilobytes of data appear in a tile.
 207 .I tiffcp
 208 attempts to set the tile dimensions so
 209 that no more than 8 kilobytes of data appear in a tile.
 210 .TP
 211 .B \-,={character}
 212 substitute {character} for ',' in parsing image directory indices
 213 in files.  This is necessary if filenames contain commas.
 214 Note that ',=' with whitespace immediately following will disable
 215 the special meaning of the ',' entirely.  See examples.
 216 .SH EXAMPLES
 217 The following concatenates two files and writes the result using
 218 .SM LZW
 219 encoding:
 220 .RS
 221 .nf
 222 tiffcp -c lzw a.tif b.tif result.tif
 223 .fi
 224 .RE
 225 .PP
 226 To convert a G3 1d-encoded
 227 .SM TIFF
 228 to a single strip of G4-encoded data the following might be used:
 229 .RS
 230 .nf
 231 tiffcp -c g4 -r 10000 g3.tif g4.tif
 232 .fi
 233 .RE
 234 (1000 is just a number that is larger than the number of rows in
 235 the source file.)
 236
 237 To extract a selected set of images from a multi-image
 238 TIFF file, the file name may be immediately followed by a ','
 239 separated list of image directory indices.  The first image
 240 is always in directory 0.  Thus, to copy the 1st and 3rd
 241 images of image file "album.tif" to "result.tif":
 242 .RS
 243 .nf
 244 tiffcp album.tif,0,2 result.tif
 245 .fi
 246 .RE
 247
 248 Given file "CCD.tif" whose first image is a noise bias
 249 followed by images which include that bias,
 250 subtract the noise from all those images following it
 251 (while decompressing) with the command:
 252 .RS
 253 .nf
 254 tiffcp -c none -b CCD.tif CCD.tif,1, result.tif
 255 .fi
 256 .RE
 257
 258 If the file above were named "CCD,X.tif", the "-,=" option would
 259 be required to correctly parse this filename with image numbers,
 260 as follows:
 261 .RS
 262 .nf
 263 tiffcp -c none -,=% -b CCD,X.tif CCD,X%1%.tif result.tif
 264 .SH "SEE ALSO"
 265 .BR pal2rgb (1),
 266 .BR tiffinfo (1),
 267 .BR tiffcmp (1),
 268 .BR tiffmedian (1),
 269 .BR tiffsplit (1),
 270 .BR libtiff (3TIFF)
 271 .PP
 272 Libtiff library home page:
 273 .BR http://www.remotesensing.org/libtiff/