img2rr is a command line application used to create reduced resolution data sets for an image. These datasets are created by iteratively downsampling the full resolution image. The results are stored using a pyramid image structure called overviews. These overview files improve the efficiency of arbitrary access to different spatial resolutions and areas of interest. This is important if you want to zoom in and out of ossim applications like OssimPlanet or ImageLinker and are critical for rapid resizing using orthoigen and igen.

Overview files created by img2rr use a ".ovr" extension. img2rr will also create a ".omd" file which contains basic radiometry information. Users also have the option to create histogram files when generating overviews. These files have a ".his" file extension.


img2rr [options] <input_file>


  --compression-quality    Compression quality varies from 0 to 100, where 100
                           is best.  Currently only for JPEG compression
  --compression-type       Compression type can be: NONE, JPEG, PACKBITS, or
  --create-histogram       Computes a histogram.
  --create-histogram-fast  Computes a histogram in fast mode which samples
                           partial tiles.
  --create-mask            Computes a mask which applies to an image for cutting
                           off black specks around the image.
  --disable-elev           Will disable the elevation
  --disable-notify         Takes an argument. Arguments are ALL, WARN, NOTICE,
                           INFO, FATAL, DEBUG.  If you want multiple disables
                           then just do multiple --disable-notify on the command
                           line.  All argument are case insensitive.  Default is
                           all are enabled.
  --disable-plugin         Will disable the plugin loader
  --histogram-bins         Number of histogram bins.   This will override the
                           default for scalar type.  Also this will force a
                           separate pass.
  --histogram-max          Maximum histogram value to use.  This will override
                           the default for scalar type.  Also this will force a
                           separate pass.
  --histogram-min          Minimum histogram value to use.  This will override
                           the default for scalar type.  Also this will force a
                           separate pass.
  --histogram-r0           Forces create-histogram code to compute a histogram
                           using r0.  If source image has reduced resolution
                           sets built in a separate pass will be made at r0.
  --list-entries           Lists the entries within the image
  --ossim-logfile          takes a logfile as an argument.  All output messages
                           are redirected to the specified log file.  By default
                           there is no log file and all messages are enabled.
  --tile-size              Defines the tile size for the supported overview
  --version                Outputs version information.
  --writer-prop            Adds a property to send to the writer. format is
  -K                       specify individual keywords to add to the preferences
                           keyword list: name=value
  -P                       specify a preference file to load
  -T                       specify the classes to trace, ex:
                           will trace ossimInit and all ossimImage classes
  -V or --version          Display version information.
  -a or --include-fullres  Wants to include full res dataset as well as reduced
                           res sets.
  -d                       Write overview to directory specified.
  -e or --entry            Give the entry(zero based) to build an overview for.
  -h or --help             Shows help
  -o                       Write overview to file specified.  If used on a
                           multi-entry file, given "foo.ovr" you will get:
  -r or --rebuild          Rebuild overviews even if they are already present.
  -s                       Stop dimension for overviews.  This controls how
                           many layers will be built. If set to 64 then the
                           builder will stop when height and width for current
                           level are less than or equal to 64.  Note a default
                           can be set in the ossim preferences file, setting the
                           keyword "overview_stop_dimension".
  -t or --type             see list at bottom for valid types. (default =

Overview Types

img2rr provides users the option to specify file format for the output overviews via the -t argument. Valid overview types include:

  • ossim_tiff_box*
  • ossim_tiff_nearest
  • gdal_tiff_nearest
  • gdal_tiff_average
  • gdal_hfa_nearest
  • gdal_hfa_average
  • ossim_kakadu_nitf_j2k

* default

Compression Options

By default, overviews are uncompressed TIFF files. However, there are several options available to create compressed overviews.

  • JPEG compression With ossim_tiff_box and ossim_tiff_nearest, you can create JPEG compressed overviews by setting "--compression-type JPEG". You can also specify the compression quality using the "--compression-quality" argument. Example:
    ossim-img2rr --compression-type JPEG --compression-quality 90 image.tif
    When using JPEG compression, null areas are replaced with black pixels (RGB 0,0,0). To retain the null pixels, you must create a mask file. Example:
    ossim-img2rr --compression-type JPEG --compression-quality 75 --create-mask image.tif
  • JPEG 2000 compression With ossim_kakadu_nitf_j2k, users have the option to create JPEG 2000 compressed NITF files. This option requires the Kakadu Plugin.
    ossim-img2rr -t ossim_kakadu_nitf_j2k --writer-prop threads=4 --writer-prop compression_quality=visually_lossless image.tif
  • ERDAS Imagine compression With gdal_hfa_nearest and gdal_hfa_average, users have the option to create overviews in ERDAS Imagine format. This option requires the GDAL Plugin.
    ossim-img2rr -t gdal_hfa_nearest image.tif

Stop Dimension

Users can control how many layers will be create by specifying a stop dimension. The stop dimension is set using the -s argument. For example, stop building overviews when both width and height are less than or equal to 64:

ossim-img2rr -s 64 <your-file>

Build overviews, specifying to stop when both width and height are less than or equal to 1:

ossim-img2rr -s 1 <your-file>

Note a default can be set in the OSSIM Preference File, setting the keyword "overview_stop_dimension".

Histogram Operations

img2rr provides an option to create a histogram when generating overviews.

  • create-histogram Computes a histogram.
  • create-histogram-fast Fast histogram computation

When creating histograms, users have the following histogram options:

  • histogram-bins Number of histogram bins.
  • histogram-max Maximum histogram value to use.
  • histogram-min Minimum histogram value to use.


ossim-img2rr -t ossim_kakadu_nitf_j2k --create-histogram-fast --histogram-r0 --entry 2 data\cadrg\cdrgxGNCJNCN_10\RPF\a.toc

Build overviews, default type = ossim_tiff_box:

ossim-img2rr <your-file>

Build overviews forcing a rebuild if already present with -r option:

ossim-img2rr -r <your-file>

Build overviews specifying the output file with -o option:

ossim-img2rr <your-file> -o foo.ovr

Build overviews specifying the output directory with -d option:

ossim-img2rr -d /tmp <your-file>

Build overviews specifying the output directory with -d option and the output file with -o option. Good for multi entry:

ossim-img2rr -d /tmp <a.toc> -o rpf-1

Build overviews specifying the type:

ossim-img2rr -t ossim_tiff_box <your-file>

Build overviews copy r0 (full res layer) (ossim_tiff types only)

ossim-img2rr -a <your-file>
Last modified 8 years ago Last modified on Oct 16, 2010 7:47:32 AM