1TIFFCROP(1)                                                        TIFFCROP(1)
2
3
4

NAME

6       tiffcrop  - select, copy, crop, convert, extract, and/or process one or
7       more TIFF files.
8

SYNOPSIS

10       tiffcrop [ options ] src1.tif ... srcN.tif dst.tif
11

DESCRIPTION

13       Tiffcrop processes one or more files created according to the Tag Image
14       File Format, Revision 6.0, specification into one or more TIFF file(s).
15       Tiffcrop is most often used to extract portions of an  image  for  pro‐
16       cessing  with  bar  code  recognizer or OCR software when that software
17       cannot restrict the region of interest to a specific portion of the im‐
18       age  or  to improve efficiency when the regions of interest must be ro‐
19       tated.  It can also be used to subdivide all or part of a processed im‐
20       age  into  smaller sections and export individual images or sections of
21       images as separate files or separate images within one  or  more  files
22       derived from the original input image or images.
23
24       The available functions can be grouped broadly into three classes:
25
26              Those  that  select individual images or sections of images from
27              the input files.  The options -N for sequences or lists of indi‐
28              vidual  images in the input files, -Z for zones, -z for regions,
29              -X and -Y for fixed sized selections, -m  for  margins,  -U  for
30              units,  and  -E  for edge reference provide a variety of ways to
31              specify portions of the input image.
32
33              Those that allow the individual images or selections to  be  ex‐
34              ported  to  one  or more output files in different groupings and
35              control the organization of the data in the output  images.  The
36              options  -P for page size grouping, -S for subdivision into col‐
37              umns and rows and -e for export mode options that produce one or
38              more  files  from  each  input image. The options -r, -s, -t, -w
39              control strip and tile format and sizes while -B -L -c -f modify
40              the  endian  addressing scheme, the compression options, and the
41              bit fill sequence of images as they are written.
42
43              Those that perform some action on each image  that  is  selected
44              from  the input file.  The options include -R for rotate, -I for
45              inversion of the photometric interpretation and/or data  values,
46              and -F to flip (mirror) the image horizontally or vertically.
47
48       Functions  are  applied  to  the input image(s) in the following order:
49       cropping, fixed area extraction, zone and region extraction, inversion,
50       mirroring, rotation.
51
52       Functions  are  applied  to the output image(s) in the following order:
53       export mode options for grouping zones, regions, or images into one  or
54       more  files,  or  row and column divisions with output margins, or page
55       size divisions with page orientation options.
56
57       Finally, strip, tile, byte order, output  resolution,  and  compression
58       options are applied to all output images.
59
60       The  output  file(s)  may be organized and compressed using a different
61       algorithm from the input files.  By default, tiffcrop will copy all the
62       understood  tags in a TIFF directory of an input file to the associated
63       directory in the output file.  Options can be used to force the  resul‐
64       tant image to be written as strips or tiles of data, respectively.
65
66       Tiffcrop  can be used to reorganize the storage characteristics of data
67       in a file, and to reorganize, extract, rotate,  and  otherwise  process
68       the  image  data  as specified at the same time whereas tiffcp does not
69       alter the image data within the file.
70
71       Using the options for selecting individual input images and the options
72       for  exporting  images  and/or  segments defined as zones or regions of
73       each input image, tiffcrop can perform  the  functions  of  tiffcp  and
74       tiffsplit  in a single pass while applying multiple operations to indi‐
75       vidual selections or images.
76

OPTIONS

78       -h     Display the syntax summary for tiffcrop.
79
80       -v     Report the  current  version  and  last  modification  date  for
81              tiffcrop.
82
83       -N odd|even|#,#-#,#|last
84              Specify  one  or  more  series or range(s) of images within each
85              file to process.  The words odd or even may be used  to  specify
86              all  odd  or  even numbered images counting from one.  Note that
87              internally, TIFF images are numbered from zero rather  than  one
88              but since this convention is not obvious to most users, tiffcrop
89              used 1 to specifiy the first image in  a  multipage  file.   The
90              word  last  may  be used in place of a number in the sequence to
91              indicate the final image in the file without  knowing  how  many
92              images there are.  Ranges of images may be specified with a dash
93              and multiple  sets  can  be  indicated  by  joining  them  in  a
94              comma-separated  list. eg. use -N 1,5-7,last to process the 1st,
95              5th through 7th, and final image in the file.
96
97       -E top|bottom|left|right
98              Specify the top, bottom, left, or right edge  as  the  reference
99              from  which  to calcuate the width and length of crop regions or
100              sequence of postions for zones. When used with the -e option for
101              exporting  zones  or  regions, the reference edge determines how
102              composite images are arranged. Using -E  left  or  right  causes
103              successive  zones  or  regions to be merged horizontally whereas
104              using -E top or bottom causes successive zones or regions to  be
105              arranged  vertically. This option has no effect on export layout
106              when multiple zones or regions are not being exported to compos‐
107              ite images. Edges may be abbreviated to the first letter.
108
109       -e combined|divided|image|multiple|separate
110              Specify the export mode for images and selections from input im‐
111              ages.  The final filename on the command line is  considered  to
112              be  the destination file or filename stem for automatically gen‐
113              erated sequences of files. Modes may be abbreviated to the first
114              letter.
115
116              combined    All  images  and  selections are written to a single
117              file with multiple selections from one  image  combined  into  a
118              single image (default)
119
120              divided     All  images  and  selections are written to a single
121              file with each selection from one image written to a new image
122
123              image      Each input image is written to a  new  file  (numeric
124              filename  sequence) with multiple selections from the image com‐
125              bined into one image
126
127              multiple   Each input image is written to a  new  file  (numeric
128              filename sequence) with each selection from the image written to
129              a new image
130
131              separate   Individual selections from each image are written  to
132              separate files
133
134       -U in|cm|px
135              Specify the type of units to apply to dimensions for margins and
136              crop regions for input and output images. Inches or  centimeters
137              are  converted  to pixels using the resolution unit specified in
138              the TIFF file (which defaults to inches if not specified in  the
139              IFD).
140
141       -m #,#,#,#
142              Specify  margins  to  be removed from the input image. The order
143              must be top, left, bottom, right with only commas separating the
144              elements  of  the list. Margins are scaled according to the cur‐
145              rent units and removed before any  other  extractions  are  com‐
146              puted..
147
148       -X #   Set  the  horizontal  (X-axis)  dimension of a region to extract
149              relative to the specified origin reference. If the origin is the
150              top or bottom edge, the X axis value will be assumed to start at
151              the left edge.
152
153       -Y #   Set the vertical (Y-axis) dimension of a region to extract rela‐
154              tive  to  the  specified  origin reference. If the origin is the
155              left or right edge, the Y axis value will be assumed to start at
156              the top.
157
158       -Z #:#,#:#
159              Specify  zones  of the image designated as position X of Y equal
160              sized portions measured from the reference edge,  eg  1:3  would
161              be first third of the image starting from the reference edge mi‐
162              nus any margins specified  for  the  confining  edges.  Multiple
163              zones  can  be specified as a comma separated list but they must
164              reference the same edge. To extract the top quarter and the bot‐
165              tom third of an image you would use -Z 1:4,3:3.
166
167       -z x1,y1,x2,y2: ... :xN,yN,xN+1,yN+1
168              Specify a series of coordinates to define regions for processing
169              and exporting.  The coordinates represent the top left and lower
170              right  corners of each region in the current units, eg inch, cm,
171              or pixels. Pixels are counted from one to width  or  height  and
172              inches or cm are calculated from image resolution data.
173
174              Each  colon delimited series of four values represents the hori‐
175              zontal and vertical offsets from the top and left edges  of  the
176              image,  regardless of the edge specified with the -E option. The
177              first and third values represent the horizontal offsets  of  the
178              corner  points  from  the  left edge while the second and fourth
179              values represent the vertical offsets from the top edge.
180
181       -F horiz|vert
182              Flip, ie mirror, the image or extracted region  horizontally  or
183              vertically.
184
185       -R 90|180|270
186              Rotate  the  image  or  extracted region 90, 180, or 270 degrees
187              clockwise.
188
189       -I [black|white|data|both]
190              Invert color space, eg dark to light for bilevel  and  grayscale
191              images.   This can be used to modify negative images to positive
192              or to correct images that have the PHOTOMETRIC_INTERPRETATIN tag
193              set  incorrectly.  If the value is black or white, the PHOTOMET‐
194              RIC_INTERPRETATION tag is set to MinIsBlack or MinIsWhite, with‐
195              out  altering  the  image data. If the argument is data or both,
196              the data values of the image are modified. Specifying  both  in‐
197              verts  the  data and the PHOTOMETRIC_INTERPRETATION tag, whereas
198              using data inverts the data but not the  PHOTOMETRIC_INTERPRETA‐
199              TION tag.  No support for modifying the color space of color im‐
200              ages in this release.
201
202       -H #   Set the horizontal resolution of output images to # expressed in
203              the current units.
204
205       -V #   Set  the vertical resolution of the output images to # expressed
206              in the current units.
207
208       -J #   Set the horizontal margin of an output page size to #  expressed
209              in  the  current units when sectioning image into columns x rows
210              subimages using the -S cols:rows option.
211
212       -K #   Set the vertical margin of an output page size to # expressed in
213              the current units when sectioning image into columns x rows sub‐
214              miages using the -S cols:rows option.
215
216       -O portrait|landscape|auto
217              Set the output orientation of the pages or sections.  Auto  will
218              use the arrangement that requires the fewest pages.  This option
219              is only meaningful in conjunction with the -P option  to  format
220              an image to fit on a specific paper size.
221
222       -P page
223              Format  the output images to fit on page size paper. Use -P list
224              to show the supported page sizes and dimensions.  You can define
225              a  custom page size by entering the width and length of the page
226              in the current units with the following format #.#x#.#.
227
228       -S cols:rows
229              Divide each image into cols across and rows down equal sections.
230
231       -B     Force output to be written with Big-Endian byte order.  This op‐
232              tion only has an effect when the output file is created or over‐
233              written and not when it is appended to.
234
235       -C     Suppress the use of ``strip chopping'' when reading images  that
236              have a single strip/tile of uncompressed data.
237
238       -c     Specify  the  compression  to use for data written to the output
239              file: none for no compression, packbits  for  PackBits  compres‐
240              sion,  lzw for Lempel-Ziv & Welch compression, jpeg for baseline
241              JPEG compression.  zip for Deflate  compression,  g3  for  CCITT
242              Group  3  (T.4) compression, and g4 for CCITT Group 4 (T.6) com‐
243              pression.  By default tiffcrop will compress data  according  to
244              the value of the Compression tag found in the source file.
245
246              The CCITT Group 3 and Group 4 compression algorithms can only be
247              used with bilevel data.
248
249              Group 3 compression  can  be  specified  together  with  several
250              T.4-specific  options:  1d  for  1-dimensional  encoding, 2d for
251              2-dimensional encoding, and fill to force each encoded  scanline
252              to  be  zero-filled  so  that the terminating EOL code lies on a
253              byte boundary.  Group 3-specific options are  specified  by  ap‐
254              pending  a  ``:''-separated  list to the ``g3'' option; e.g.  -c
255              g3:2d:fill to get 2D-encoded data with byte-aligned EOL codes.
256
257              LZW compression can  be  specified  together  with  a  predictor
258              value.   A predictor value of 2 causes each scanline of the out‐
259              put image to undergo horizontal differencing before  it  is  en‐
260              coded;  a  value of 1 forces each scanline to be encoded without
261              differencing.  LZW-specific options are specified by appending a
262              ``:''-separated  list  to the ``lzw'' option; e.g.  -c lzw:2 for
263              LZW compression with horizontal differencing.
264
265       -f     Specify the bit fill order to use in writing  output  data.   By
266              default,  tiffcrop will create a new file with the same fill or‐
267              der as the original.  Specifying -f lsb2msb will force  data  to
268              be  written  with  the  FillOrder  tag  set to LSB2MSB, while -f
269              msb2lsb will force data to be written with the FillOrder tag set
270              to MSB2LSB.
271
272       -i     Ignore  non-fatal read errors and continue processing of the in‐
273              put file.
274
275       -k size
276              Set maximum memory allocation size  (in  MiB).  The  default  is
277              256MiB.  Set to 0 to disable the limit.
278
279       -l     Specify  the length of a tile (in pixels).  Tiffcrop attempts to
280              set the tile dimensions so that no more than 8 kilobytes of data
281              appear in a tile.
282
283       -L     Force  output to be written with Little-Endian byte order.  This
284              option only has an effect when the output  file  is  created  or
285              overwritten and not when it is appended to.
286
287       -M     Suppress the use of memory-mapped files when reading images.
288
289       -p     Specify  the  planar  configuration to use in writing image data
290              that has more than one sample per pixel.  By  default,  tiffcrop
291              will create a new file with the same planar configuration as the
292              original.  Specifying -p contig will force data  to  be  written
293              with  multi-sample  data packed together, while -p separate will
294              force samples to be written in separate planes.
295
296       -r     Specify the number of rows (scanlines) in  each  strip  of  data
297              written  to  the  output  file.   By default (or when value 0 is
298              specified), tiffcrop attempts to set the rows/strip that no more
299              than  8  kilobytes of data appear in a strip. If you specify the
300              special value -1 it will results in infinite number of the  rows
301              per strip. The entire image will be the one strip in that case.
302
303       -s     Force  the  output  file  to  be  written with data organized in
304              strips (rather than tiles).
305
306       -t     Force the output file to be written with data organized in tiles
307              (rather than strips).
308
309       -w     Specify  the  width of a tile (in pixels).  tiffcrop attempts to
310              set the tile dimensions so that no more than 8 kilobytes of data
311              appear  in a tile.  tiffcrop attempts to set the tile dimensions
312              so that no more than 8 kilobytes of data appear in a tile.
313
314       Debug and dump facility
315              -D opt1:value1,opt2:value2,opt3:value3:opt4:value4 Display  pro‐
316              gram  progress  and/or dump raw data to non-TIFF files.  Options
317              include the following and must be joined as  a  comma  separated
318              list. The use of this option is generally limited to program de‐
319              bugging and development of future options. An equal sign may  be
320              substituted for the colon in option:value pairs.
321
322              debug:N          Display  limited  program  progress  indicators
323              where larger N increase the level of detail.
324
325              format:txt|raw  Format any logged data as ASCII text or raw  bi‐
326              nary values. ASCII text dumps include strings of ones and zeroes
327              representing the binary values in the image data plus  identify‐
328              ing headers.
329
330              level:N          Specify  the  level  of detail presented in the
331              dump files.  This can vary from dumps of  the  entire  input  or
332              output  image  data to dumps of data processed by specific func‐
333              tions. Current range of levels is 1 to 3.
334
335              input:full-path-to-directory/input-dumpname
336
337              output:full-path-to-directory/output-dumpname
338
339              When dump files are being written, each image will be written to
340              a separate file with the name built by adding a numeric sequence
341              value to the dumpname and an extension of .txt for  ASCII  dumps
342              or .bin for binary dumps.
343
344              The  four  debug/dump  options  are independent, though it makes
345              little sense to specify a dump file without specifying a  detail
346              level.
347
348              Note:  Tiffcrop may be compiled with -DDEVELMODE to enable addi‐
349              tional very
350               low level debug reporting.
351

EXAMPLES

353       The following concatenates two files and writes the  result  using  LZW
354       encoding:
355              tiffcrop -c lzw a.tif b.tif result.tif
356
357       To  convert  a  G3 1d-encoded TIFF to a single strip of G4-encoded data
358       the following might be used:
359              tiffcrop -c g4 -r 10000 g3.tif g4.tif
360       (1000 is just a number that is larger than the number of  rows  in  the
361       source file.)
362
363       To  extract  a  selected set of images from a multi-image TIFF file use
364       the -N option described above. Thus, to copy the 1st and 3rd images  of
365       image file "album.tif" to "result.tif":
366              tiffcrop -N 1,3 album.tif result.tif
367
368       Invert a bilevel image scan of a microfilmed document and crop off mar‐
369       gins of 0.25 inches on the left and right, 0.5 inch  on  the  top,  and
370       0.75  inch  on the bottom. From the remaining portion of the image, se‐
371       lect the second and third quarters, ie, one half of the area left  from
372       the center to each margin.
373              tiffcrop  -U in -m 0.5,0.25,0.75,0.25 -E left -Z 2:4,3:4 -I both
374              MicrofilmNegative.tif MicrofilmPostiveCenter.tif
375
376       Extract only the final image of a large Architectural E sized multipage
377       TIFF  file  and  rotate  it 90 degrees clockwise while reformatting the
378       output to fit on tabloid sized sheets with one quarter of  an  inch  on
379       each side:
380              tiffcrop  -N last -R 90 -O auto -P tabloid -U in -J 0.25 -K 0.25
381              -H 300 -V 300 Big-PlatMap.tif BigPlatMap-Tabloid.tif
382       The output images will have a specified resolution of 300 dpi  in  both
383       directions.  The  orientation of each page will be determined by which‐
384       ever choice requires the fewest pages. To specify a  specific  orienta‐
385       tion,  use the portrait or landscape option. The paper size option does
386       not resample the image. It breaks each original image into a series  of
387       smaller  images that will fit on the target paper size at the specified
388       resolution.
389
390       Extract two regions 2048 pixels wide by 2048 pixels high from each page
391       of  a  multi-page input file and write each region to a separate output
392       file.
393              tiffcrop -U px  -z  1,1,2048,2048:1,2049,2048,4097  -e  separate
394              CheckScans.tiff Check
395       The  output  file  names  will use the stem Check with a numeric suffix
396       which is incremented for each region of each image, eg  Check-001.tiff,
397       Check-002.tiff  ...   Check-NNN.tiff. To produce a unique file for each
398       page of the input image with one new image for each region of the input
399       image on that page, change the export option to -e multiple.
400
401

NOTES

403       In general, bilevel, grayscale, palette and RGB(A) data with bit depths
404       from 1 to 32 bits should work in both interleaved  and  separate  plane
405       formats.  Unlike  tiffcp, tiffcrop can read and write tiled images with
406       bits per sample that are not a multiple of 8 in  both  interleaved  and
407       separate  planar format. Floating point data types are supported at bit
408       depts of 16, 24, 32 and 64 bits per sample.
409
410       Not all images can be converted from one compression scheme to another.
411       Data  with  some photometric interpretations and/or bit depths are tied
412       to specific compression schemes and vice-versa, e.g. Group 3/4 compres‐
413       sion  is  only usable for bilevel data. JPEG compression is only usable
414       on 8 bit per sample data (or 12 bit if LibTIFF was compiled with 12 bit
415       JPEG  support).  Support  for OJPEG compressed images is problematic at
416       best. Since OJPEG compression is no longer supported for writing images
417       with  LibTIFF,  these images will be updated to the newer JPEG compres‐
418       sion when they are copied or processed. This may cause the image to ap‐
419       pear color shifted or distorted after conversion.  In some cases, it is
420       possible to remove the original compression from image data  using  the
421       option -cnone.
422
423       Tiffcrop does not currently provide options to up or downsample data to
424       different bit depths or convert data from one  photometric  interpreta‐
425       tion to another, e.g. 16 bits per sample to 8 bits per sample or RGB to
426       grayscale.
427
428       Tiffcrop is very loosely derived from code  in  tiffcp  with  extensive
429       modifications  and  additions  to support the selection of input images
430       and regions and the exporting of them to one or more  output  files  in
431       various groupings. The image manipulation routines are entirely new and
432       additional ones may be added in the future. It will handle tiled images
433       with bit depths that are not a multiple of eight that tiffcp may refuse
434       to read.
435
436       Tiffcrop was designed to handle large files  containing  many  moderate
437       sized images with memory usage that is independent of the number of im‐
438       ages in the file.  In order to support compression modes that  are  not
439       based  on individual scanlines, e.g. JPEG, it now reads images by strip
440       or tile rather than by indvidual scanlines. In addition to  the  memory
441       required by the input and output buffers associated with LibTIFF one or
442       more buffers at least as large as the largest image to be read are  re‐
443       quired.  The  design  favors large volume document processing uses over
444       scientific or graphical manipulation of  large  datasets  as  might  be
445       found in research or remote sensing scenarios.
446

SEE ALSO

448       pal2rgb(1),  tiffinfo(1),  tiffcmp(1), tiffcp(1), tiffmedian(1), tiffs‐
449       plit(1), libtiff(3TIFF)
450
451       Libtiff library home page: http://www.simplesystems.org/libtiff/
452
453
454
455
456libtiff                         December, 2008                     TIFFCROP(1)
Impressum