1 .\" tiffcrop -- a port of tiffcp.c extended to include extended processing of images
5 .\" Copyright (c) 1988-1997 Sam Leffler
6 .\" Copyright (c) 1991-1997 Silicon Graphics, Inc.
8 .\" Permission to use, copy, modify, distribute, and sell this software and
9 .\" its documentation for any purpose is hereby granted without fee, provided
10 .\" that (i) the above copyright notices and this permission notice appear in
11 .\" all copies of the software and related documentation, and (ii) the names of
12 .\" Sam Leffler and Silicon Graphics may not be used in any advertising or
13 .\" publicity relating to the software without the specific, prior written
14 .\" permission of Sam Leffler and Silicon Graphics.
16 .\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
17 .\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
18 .\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
20 .\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
21 .\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
22 .\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
23 .\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
24 .\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
27 .\" Additional code Copyright (c) 2006-2009 Richard Nolde
28 .\" Lasted Updated 9/2009
30 .TH "TIFFCROP" "1" "December, 2008" "libtiff" ""
32 tiffcrop \- select, copy, crop, convert, extract, and/or process one or more
40 .I "src1.tif ... srcN.tif dst.tif"
43 processes one or more files created according
44 to the Tag Image File Format, Revision 6.0, specification
49 is most often used to extract portions of an image for processing
50 with bar code recognizer or OCR software when that software cannot
51 restrict the region of interest to a specific portion of the image
52 or to improve efficiency when the regions of interest must be rotated.
53 It can also be used to subdivide all or part of a processed image into
54 smaller sections and export individual images or sections of images
55 as separate files or separate images within one or more files derived
56 from the original input image or images.
58 The available functions can be grouped broadly into three classes:
60 Those that select individual images or sections of images from the input files.
61 The options \-N for sequences or lists of individual images in the input files,
62 \-Z for zones, \-z for regions, \-X and \-Y for fixed sized selections,
63 \-m for margins, \-U for units, and \-E for edge reference provide a variety of
64 ways to specify portions of the input image.
66 Those that allow the individual images or selections to be exported to one or
67 more output files in different groupings and control the organization of the
68 data in the output images. The options \-P for page size grouping, \-S for
69 subdivision into columns and rows and \-e for export mode options that produce
70 one or more files from each input image. The options \-r, \-s, \-t, \-w control
71 strip and tile format and sizes while \-B \-L \-c \-f modify the endian addressing
72 scheme, the compression options, and the bit fill sequence of images as they
75 Those that perform some action on each image that is selected from the input file.
76 The options include \-R for rotate, \-I for inversion of the photometric
77 interpretation and/or data values, and \-F to flip (mirror) the image horizontally
81 Functions are applied to the input image(s) in the following order:
82 cropping, fixed area extraction, zone and region extraction,
83 inversion, mirroring, rotation.
85 Functions are applied to the output image(s) in the following order:
86 export mode options for grouping zones, regions, or images into
89 row and column divisions with output margins,
91 page size divisions with page orientation options.
93 Finally, strip, tile, byte order, output resolution, and compression options are
94 applied to all output images.
96 The output file(s) may be organized and compressed using a different
97 algorithm from the input files.
100 will copy all the understood tags in a
102 directory of an input file to the associated directory in the output file.
103 Options can be used to force the resultant image to be written as strips
104 or tiles of data, respectively.
107 can be used to reorganize the storage characteristics of data
108 in a file, and to reorganize, extract, rotate, and otherwise
109 process the image data as specified at the same time whereas
110 tiffcp does not alter the image data within the file.
112 Using the options for selecting individual input images and the
113 options for exporting images and/or segments defined as zones or
114 regions of each input image,
116 can perform the functions of tiffcp and tiffsplit in a single pass
117 while applying multiple operations to individual selections or images.
122 Display the syntax summary for tiffcrop.
125 Report the current version and last modification date for tiffcrop.
127 .B \-N odd|even|#,#\-#,#|last
128 Specify one or more series or range(s) of images within each file to process.
133 may be used to specify all odd or even numbered images counting from one.
134 Note that internally, TIFF images are numbered from zero rather than one
135 but since this convention is not obvious to most users, tiffcrop used 1
136 to specifiy the first image in a multipage file. The word
138 may be used in place of a number in the sequence to indicate the
139 final image in the file without knowing how many images there are.
140 Ranges of images may be specified with a dash and multiple sets
141 can be indicated by joining them in a comma\-separated list. eg. use
143 to process the 1st, 5th through 7th, and final image in the file.
145 .B \-E top|bottom|left|right
146 Specify the top, bottom, left, or right edge as the reference from
147 which to calcuate the width and length of crop regions or sequence
148 of postions for zones. When used with the \-e option for exporting
149 zones or regions, the reference edge determines how composite images
150 are arranged. Using \-E left or right causes successive zones or
151 regions to be merged horizontally whereas using \-E top or bottom
152 causes successive zones or regions to be arranged vertically. This
153 option has no effect on export layout when multiple zones or regions
154 are not being exported to composite images. Edges may be abbreviated
157 .B \-e combined|divided|image|multiple|separate
158 Specify the export mode for images and selections from input images.
159 The final filename on the command line is considered to be the
160 destination file or filename stem for automatically generated
161 sequences of files. Modes may be abbreviated to the first letter.
163 combined All images and selections are written to a single file with
164 multiple selections from one image combined into a single image (default)
166 divided All images and selections are written to a single file
167 with each selection from one image written to a new image
169 image Each input image is written to a new file (numeric filename sequence)
170 with multiple selections from the image combined into one image
172 multiple Each input image is written to a new file (numeric filename sequence)
173 with each selection from the image written to a new image
175 separate Individual selections from each image are written to separate files
178 Specify the type of units to apply to dimensions for margins and
179 crop regions for input and output images. Inches or centimeters
180 are converted to pixels using the resolution unit specified in the
181 TIFF file (which defaults to inches if not specified in the IFD).
184 Specify margins to be removed from the input image. The order must
185 be top, left, bottom, right with only commas separating the elements
186 of the list. Margins are scaled according to the current units and
187 removed before any other extractions are computed..
190 Set the horizontal (X\-axis) dimension of a region to extract relative to
191 the specified origin reference. If the origin is the top or bottom
192 edge, the X axis value will be assumed to start at the left edge.
195 Set the vertical (Y\-axis) dimension of a region to extract relative to
196 the specified origin reference. If the origin is the left or right
197 edge, the Y axis value will be assumed to start at the top.
200 Specify zones of the image designated as position X of Y equal sized portions
201 measured from the reference edge, eg 1:3 would be first third of the
202 image starting from the reference edge minus any margins specified
203 for the confining edges. Multiple zones can be specified as a comma
204 separated list but they must reference the same edge. To extract the
205 top quarter and the bottom third of an image you would use
208 .B \-z x1,y1,x2,y2: ... :xN,yN,xN+1,yN+1
209 Specify a series of coordinates to define regions for processing and exporting.
210 The coordinates represent the top left and lower right corners of each region
211 in the current units, eg inch, cm, or pixels. Pixels are counted from one to
212 width or height and inches or cm are calculated from image resolution data.
214 Each colon delimited series of four values represents the horizontal and vertical
215 offsets from the top and left edges of the image, regardless of the edge specified
216 with the \-E option. The first and third values represent the horizontal offsets of
217 the corner points from the left edge while the second and fourth values represent
218 the vertical offsets from the top edge.
221 Flip, ie mirror, the image or extracted region horizontally or vertically.
224 Rotate the image or extracted region 90, 180, or 270 degrees clockwise.
226 .B \\-I [black|white|data|both]
227 Invert color space, eg dark to light for bilevel and grayscale images.
228 This can be used to modify negative images to positive or to correct
229 images that have the PHOTOMETRIC_INTERPRETATIN tag set incorrectly.
230 If the value is black or white, the PHOTOMETRIC_INTERPRETATION tag is set to
231 MinIsBlack or MinIsWhite, without altering the image data. If the argument
232 is data or both, the data values of the image are modified. Specifying both
233 inverts the data and the PHOTOMETRIC_INTERPRETATION tag, whereas using data
234 inverts the data but not the PHOTOMETRIC_INTERPRETATION tag.
235 No support for modifying the color space of color images in this release.
238 Set the horizontal resolution of output images to #
239 expressed in the current units.
242 Set the vertical resolution of the output images to #
243 expressed in the current units.
246 Set the horizontal margin of an output page size to #
247 expressed in the current units when sectioning image into columns x rows
248 subimages using the \-S cols:rows option.
251 Set the vertical margin of an output page size to #
252 expressed in the current units when sectioning image into columns x rows
253 submiages using the \-S cols:rows option.
255 .B \-O portrait|landscape|auto
256 Set the output orientation of the pages or sections.
257 Auto will use the arrangement that requires the fewest pages.
258 This option is only meaningful in conjunction with the -P
259 option to format an image to fit on a specific paper size.
262 Format the output images to fit on page size paper. Use
263 \-P list to show the supported page sizes and dimensions.
264 You can define a custom page size by entering the width and length of the
265 page in the current units with the following format #.#x#.#.
268 Divide each image into cols across and rows down equal sections.
271 Force output to be written with Big\-Endian byte order.
272 This option only has an effect when the output file is created or
273 overwritten and not when it is appended to.
276 Suppress the use of ``strip chopping'' when reading images
277 that have a single strip/tile of uncompressed data.
280 Specify the compression to use for data written to the output file:
284 for PackBits compression,
286 for Lempel\-Ziv & Welch compression,
288 for baseline JPEG compression.
290 for Deflate compression,
292 for CCITT Group 3 (T.4) compression,
295 for CCITT Group 4 (T.6) compression.
298 will compress data according to the value of the
300 tag found in the source file.
304 Group 3 and Group 4 compression algorithms can only
305 be used with bilevel data.
307 Group 3 compression can be specified together with several
308 T.4\-specific options:
310 for 1\-dimensional encoding,
312 for 2\-dimensional encoding,
315 to force each encoded scanline to be zero\-filled so that the
316 terminating EOL code lies on a byte boundary.
317 Group 3\-specific options are specified by appending a ``:''\-separated
318 list to the ``g3'' option; e.g.
320 to get 2D\-encoded data with byte\-aligned EOL codes.
323 compression can be specified together with a
326 A predictor value of 2 causes
327 each scanline of the output image to undergo horizontal
328 differencing before it is encoded; a value
329 of 1 forces each scanline to be encoded without differencing.
330 LZW\-specific options are specified by appending a ``:''\-separated
331 list to the ``lzw'' option; e.g.
335 compression with horizontal differencing.
338 Specify the bit fill order to use in writing output data.
341 will create a new file with the same fill order as the original.
344 will force data to be written with the FillOrder tag set to
348 will force data to be written with the FillOrder tag set to
352 Ignore non\-fatal read errors and continue processing of the input file.
355 Specify the length of a tile (in pixels).
357 attempts to set the tile dimensions so
358 that no more than 8 kilobytes of data appear in a tile.
361 Force output to be written with Little\-Endian byte order.
362 This option only has an effect when the output file is created or
363 overwritten and not when it is appended to.
366 Suppress the use of memory\-mapped files when reading images.
369 Specify the planar configuration to use in writing image data
370 that has more than one sample per pixel.
373 will create a new file with the same planar configuration as
377 will force data to be written with multi\-sample data packed
380 will force samples to be written in separate planes.
383 Specify the number of rows (scanlines) in each strip of data
384 written to the output file.
385 By default (or when value
389 attempts to set the rows/strip that no more than 8 kilobytes of
390 data appear in a strip. If you specify the special value
392 it will results in infinite number of the rows per strip. The entire image
393 will be the one strip in that case.
396 Force the output file to be written with data organized in strips
400 Force the output file to be written with data organized in tiles
401 (rather than strips).
404 Specify the width of a tile (in pixels).
406 attempts to set the tile dimensions so
407 that no more than 8 kilobytes of data appear in a tile.
409 attempts to set the tile dimensions so
410 that no more than 8 kilobytes of data appear in a tile.
412 Debug and dump facility
413 .B \-D opt1:value1,opt2:value2,opt3:value3:opt4:value4
414 Display program progress and/or dump raw data to non\-TIFF files.
415 Options include the following and must be joined as a comma
416 separated list. The use of this option is generally limited to
417 program debugging and development of future options. An equal sign
418 may be substituted for the colon in option:value pairs.
420 debug:N Display limited program progress indicators where larger N
421 increase the level of detail.
423 format:txt|raw Format any logged data as ASCII text or raw binary
424 values. ASCII text dumps include strings of ones and zeroes representing
425 the binary values in the image data plus identifying headers.
427 level:N Specify the level of detail presented in the dump files.
428 This can vary from dumps of the entire input or output image data to dumps
429 of data processed by specific functions. Current range of levels is 1 to 3.
431 input:full\-path\-to\-directory/input\-dumpname
433 output:full\-path\-to\-directory/output\-dumpname
435 When dump files are being written, each image will be written to a separate
436 file with the name built by adding a numeric sequence value to the dumpname
437 and an extension of .txt for ASCII dumps or .bin for binary dumps.
439 The four debug/dump options are independent, though it makes little sense to
440 specify a dump file without specifying a detail level.
442 Note: Tiffcrop may be compiled with -DDEVELMODE to enable additional very
443 low level debug reporting.
445 The following concatenates two files and writes the result using
450 tiffcrop \-c lzw a.tif b.tif result.tif
454 To convert a G3 1d\-encoded
456 to a single strip of G4\-encoded data the following might be used:
459 tiffcrop \-c g4 \-r 10000 g3.tif g4.tif
462 (1000 is just a number that is larger than the number of rows in
465 To extract a selected set of images from a multi\-image TIFF file
466 use the \-N option described above. Thus, to copy the 1st and 3rd
467 images of image file "album.tif" to "result.tif":
470 tiffcrop \-N 1,3 album.tif result.tif
474 Invert a bilevel image scan of a microfilmed document and crop off margins of
475 0.25 inches on the left and right, 0.5 inch on the top, and 0.75 inch on the
476 bottom. From the remaining portion of the image, select the second and third
477 quarters, ie, one half of the area left from the center to each margin.
479 tiffcrop \-U in \-m 0.5,0.25,0.75,0.25 \-E left \-Z 2:4,3:4 \-I both MicrofilmNegative.tif MicrofilmPostiveCenter.tif
483 Extract only the final image of a large Architectural E sized
484 multipage TIFF file and rotate it 90 degrees clockwise while
485 reformatting the output to fit on tabloid sized sheets with one
486 quarter of an inch on each side:
488 tiffcrop \-N last \-R 90 \-O auto \-P tabloid \-U in \-J 0.25 \-K 0.25 \-H 300 \-V 300 Big\-PlatMap.tif BigPlatMap\-Tabloid.tif
491 The output images will have a specified resolution of 300 dpi in both
492 directions. The orientation of each page will be determined by whichever
493 choice requires the fewest pages. To specify a specific orientation, use
494 the portrait or landscape option. The paper size option does not resample
495 the image. It breaks each original image into a series of smaller images
496 that will fit on the target paper size at the specified resolution.
500 Extract two regions 2048 pixels wide by 2048 pixels high from each page of
501 a multi\-page input file and write each region to a separate output file.
503 tiffcrop \-U px \-z 1,1,2048,2048:1,2049,2048,4097 \-e separate CheckScans.tiff Check
506 The output file names will use the stem Check with a numeric suffix which is
507 incremented for each region of each image, eg Check\-001.tiff, Check\-002.tiff ...
508 Check\-NNN.tiff. To produce a unique file for each page of the input image
509 with one new image for each region of the input image on that page, change
510 the export option to \-e multiple.
514 In general, bilevel, grayscale, palette and RGB(A) data with bit depths
515 from 1 to 32 bits should work in both interleaved and separate plane
516 formats. Unlike tiffcp, tiffcrop can read and write tiled images with
517 bits per sample that are not a multiple of 8 in both interleaved and
518 separate planar format. Floating point data types are supported at
519 bit depts of 16, 24, 32 and 64 bits per sample.
521 Not all images can be converted from one compression scheme to another.
522 Data with some photometric interpretations and/or bit depths are tied to
523 specific compression schemes and vice-versa, e.g. Group 3/4 compression
524 is only usable for bilevel data. JPEG compression is only usable on 8
525 bit per sample data (or 12 bit if
527 was compiled with 12 bit JPEG support). Support for OJPEG compressed
528 images is problematic at best. Since OJPEG compression is no longer
529 supported for writing images with LibTIFF, these images will be updated
530 to the newer JPEG compression when they are copied or processed. This
531 may cause the image to appear color shifted or distorted after conversion.
532 In some cases, it is possible to remove the original compression from
533 image data using the option -cnone.
535 Tiffcrop does not currently provide options to up or downsample data to
536 different bit depths or convert data from one photometric interpretation
537 to another, e.g. 16 bits per sample to 8 bits per sample or RGB to grayscale.
539 Tiffcrop is very loosely derived from code in
541 with extensive modifications and additions to support the selection of input
542 images and regions and the exporting of them to one or more output files in
543 various groupings. The image manipulation routines are entirely new and
544 additional ones may be added in the future. It will handle tiled images with
545 bit depths that are not a multiple of eight that tiffcp may refuse to read.
548 was designed to handle large files containing many moderate sized images
549 with memory usage that is independent of the number of images in the file.
550 In order to support compression modes that are not based on individual
551 scanlines, e.g. JPEG, it now reads images by strip or tile rather than by
552 indvidual scanlines. In addition to the memory required by the input and
553 output buffers associated with
555 one or more buffers at least as large as the largest image to be read are
556 required. The design favors large volume document processing uses over
557 scientific or graphical manipulation of large datasets as might be found
558 in research or remote sensing scenarios.
568 Libtiff library home page:
569 .BR http://www.remotesensing.org/libtiff/
projects / wxWidgets.git / blob