Home

User Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Contributor Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Quick Links

Software Manual
AstroDiscuss
GitHub
API Reference

Documentation Versions


ISIS 2

Documentation
Tutorials
Technical Documents
USGS

ISIS Application Documentation


grid

Printer Friendly View | TOC | Home

Add a graticule or rectangular grid to the input image

Overview Parameters Example 1 Example 2 Example 3

Description

This program superimposes a user-defined grid on an input image.

Two types of grids are available:
1. A graticule based on latitude and longitude coordinates where (MODE=GROUND).
2. A simple rectangular grid based on line and sample coordinates where (MODE=IMAGE).
Defaults:
  • MODE = GROUND
  • BASELAT = 0.0
  • BASELON = 0.0
  • LATINC = 10
  • LONINC = 10
Use the GROUND mode for images that have SPICE or map projection information. Use the IMAGE mode for images that do not have SPICE or map projection information, or to draw grid lines based on sample and line information.

The grid pattern will intersect a specific origin of either (latitude,longitude) or (sample,line) position. Grid lines are drawn at intervals from the origin based on the increment values defined by the user. The graticule produced may not match the image coordinates exactly, so the result will have outer grid cells that might have different heights and widths than the interior grid cells. In addition, if the LATINC and LONINC are too large compared with your image map scale, the grid lines may miss your image. If the increments are too small, the grid lines may be overly dense.

This application will draw grids on either ISIS level0, level1 (with successful spiceinit), and level2 cubes, or mosaics. The mapping information in the labels will be used to draw grid lines on mosaics and Level2 images. If the latitude and longitude information cannot be calculated or extracted using the image label contents, then use the IMAGE mode.

For Cubes with an associated band-dependent camera model (latitude, longitude coordinates do not correspond to the same sample, line coordinates in each band,) the grid is recalculated for each band.

Example Parameter Settings for Grids:
Example 1: Superimpose a basic latitude/longitude graticule with grid lines drawn every 10 degrees based on zero:
MODE=GROUND BASELAT=0 BASELON=0 LATINC=10 LONINC=10

Example 2: Superimpose a graticule on an input image that intersects at line 23 and sample 17, with vertical lines drawn every 30 pixels and horizontal lines every 40 pixels:
MODE=IMAGE BASELINE=23 BASESAMPLE=17 SINC=30 LINC=40
Note: MODE=GROUND cannot be used when sample and line coordinates are used.

Example 3: Superimpose a latitude/longitude graticule with a grid intersection at -5.0 degree latitude and 140.0 degree longitude, with latitude lines drawn every 2.5 degrees and longitude lines drawn every 3 degrees:
MODE=GROUND BASELAT=-5.0 BASELON=140 LATINC=2.5 LONINC=3

Example 4: Superimpose a latitude/longitude graticule within a subarea of an image (full latitude and longitude extent), with a grid line drawn every 2.5 degrees between latitudes -8 and -1 degrees and only between longitudes 140 and 145 degrees:
MODE=GROUND BASELAT=0 BASELON=0 LATINC=2.5 LONINC=2.5 MINLAT=-8 MAXLAT=-1 MINLON=140 MAXLON=145 Bound=yes

For complex grids, the grid application can be run multiple times with different parameter settings for each successive run that builds onto the previous output file. The TICKS option can be used to draw short ticks instead of grid lines. The OUTLINE option will draw grid lines along the outside edges of the first and last samples and lines of the input file. The BOUNDARY option will either draw grid lines around the outside edges of the input file or around the bounding box specified by the user with MINLAT, MAXLAT, MINLON, and MAXLON parameters.


Categories


Related Objects and Documents

Applications


History

Sean Crosby2007-03-16 Original version
Steven Lambright2007-07-27 Added category: Map Projection
Steven Lambright2008-04-22 Fixed problems with mapping outside of the projection space and with 0lat/0lon boundaries.
Steven Lambright2008-05-12 Removed references to CubeInfo
Steven Lambright2008-06-12 Added outline option
Steven Lambright2009-01-06 Changed how mode=ground works
Steven Lambright2010-05-06 Added TICKS options
Steven Lambright2010-07-22 Added LINEWIDTH option
Mackenzie Boyd2011-01-21 Added more line options, to change output to be HRS, LRS, NULL, or a DN.
Steven Lambright2011-01-25 Bug fixes for projections that use PositiveWest or Planetographic coordinate systems. The BASELAT and BASELON parameters are now expected to be in the units of the projection (if your cube has a planetographic latitude system, and baselat=50, then there will be a line at the planetographic latitude of 50).
Steven Lambright2011-01-26 Added BOUNDARY, MINLAT, MAXLAT, MINLON and MAXLON options.
Steven Lambright2011-12-08 Fixed a bug with the outline option. If the image had a larger number of samples than number of lines, all of the data at sample > number of lines would be considered a grid line. This could result in a large portion of the image losing legitimate DN values for the grid value. Fixes #607.
Steven Lambright2012-01-04 Tested and documented for the January 2012 release. The documentation updates included were recommended by Chris Isbell.
Adam Licht2012-12-26 Added functionality to choose the source of image background. Pixel Values for behind the grid can now be the image pixel value, HRS, LRS, NULL, or a DN.
Steven Lambright2012-12-31 Incorporated Adam Licht's changes into Isis. This included re-formatting to match current Isis 3 coding standards, removal of error checking of conditions that cannot happen, fixes with running in batch mode/resetting of variable states between runs, some re-positioning of parameter locations, and creating tests. These changes shouldn't break any existing scripts that utilize grid. Fixes #917.
Moses Milazzo2013-03-24 Added to documentation to alert the user to the fact that providing a poorly chosen starting point or grid increment may result in unexpected behavior. Fixes #178.
Ella Mae Lee2013-07-18 Updated the documentation and added examples. Fixes #178.
Janet Barrett2014-06-23 Modified so that the output cube characteristics are obtained from the input cube and/or cube characteristics specified on the command line. Fixes #2063.
Kristin Berry2014-11-25 Modified to work on Cubes with associated band-dependent camera models. Now when MODE="GROUND" on a Cube with a band-dependent camera model, the grid will be re-calculated for each band. Fixes #2191.
Kristin Berry2017-02-16 Fixed error introduced in last change which caused grid to no longer work on multi-band cubes without camera models (for example: a mosaic will not have a camera model.) Fixes #4586.
Jesse Mapel2017-06-26 Added a flag to extend the grid past the longitude domain boundary. Fixes #2185.
Kaitlyn Lee2020-10-26 Converted application and tests for Gtest conversion.

Parameter Groups

Files

Name Description
FROM Input cube
TO Output cube

Grid Type

Name Description
MODEGrid options
TICKSDraw ticks instead of lines
OUTLINEOutline the image
BOUNDARYInclude grid lines at the lat/lon extent of the image or as defined by the ground options
EXTENDGRIDIf the grid should be extended past the longitude domain boundary.

Image Grid Parameters

Name Description
BASELINEStarting line
BASESAMPLEStarting sample
LINCLine increment
SINCSample increment

Ground Grid Parameters

Name Description
BASELATStarting latitude
BASELONStarting longitude
LATINCLatitude increment
LONINCLongitude increment

Ground Grid Limits

Name Description
MINLATLowest latitude value to extend grid lines
MAXLATHighest latitude value to extend grid lines
MINLONLowest longitude value to extend grid lines
MAXLONHighest longitude value to extend grid lines

Line Parameters

Name Description
LINEWIDTHThickness of lines (pixels)
LINEVALUESelect grid line value assignment option
DNVALUEDN value to be used

Background Type

Name Description
BKGNDVALUESelect background DN value assignment option
BKGNDDNVALUEDN value to be used

Tick Parameters

Name Description
DIAGONALTICKSDraw tick marks diagonally ('x' instead of '+')
TICKSIZESize (length) of tickmarks (pixels)
X

Files: FROM


Description

Use this parameter to select the input file.

Type cube
File Mode input
Filter *.cub
Close Window
X

Files: TO


Description

This file will contain the gridded image.

Type cube
File Mode output
Filter *.cub
Close Window
X

Grid Type: MODE


Description

This allows for selection of either IMAGE or GROUND coordinates when drawing the grid.

Type string
Default GROUND
Option List:
Option Brief Description
IMAGEAdd a rectangular grid in terms of lines and samples A grid will be inserted into the image with spacing and position defined in line and sample coordinates.

Exclusions

  • BASELAT
  • BASELON
  • LATINC
  • LONINC
  • MINLAT
  • MAXLAT
  • MINLON
  • MAXLON
  • BOUNDARY
GROUNDAdd a grid (graticule) in terms of lat/lon coordinates A grid will be inserted into the image with spacing and position defined in latitude and longitude coordinates.

Exclusions

  • LINC
  • SINC
  • BASELINE
  • BASESAMPLE
Close Window
X

Grid Type: TICKS


Description

Draw ticks at grid line intersections (instead of drawing full lines).

Type boolean
Default false
Inclusions
  • DIAGONALTICKS
  • TICKSIZE
Close Window
X

Grid Type: OUTLINE


Description

This will draw grid lines at the very edges of the image.

Type boolean
Default false
Close Window
X

Grid Type: BOUNDARY


Description

This will draw grid lines (or ticks) at the lat/lon extents of the image or those extents as provided by user input MINLAT, MAXLAT, MINLON, and MAXLON.

Type boolean
Default false
Close Window
X

Grid Type: EXTENDGRID


Description

If false, the grid will stop at the longitude domain boundary, -180 to 180 or 0 to 360, if the minimum or maximum longitude values are outside of the domain range. If true, the grid will extend all the way to the minimum and maximum longitudes regardless of the domain.

Type boolean
Default false
Close Window
X

Image Grid Parameters: BASELINE


Description

Starting line of grid. This, along with BASESAMPLE, defines the starting point (line) for drawing the grid.

Type integer
Default 1
Minimum 1 (inclusive)
Close Window
X

Image Grid Parameters: BASESAMPLE


Description

Starting sample of grid. This, along with BASELINE, defines the starting point (sample) for drawing the grid.

Type integer
Default 1
Minimum 1 (inclusive)
Close Window
X

Image Grid Parameters: LINC


Description

This defines the line increment when drawing the grid, starting at BASELINE. The line increment is the spacing between lines.

Type integer
Default 100
Minimum 1 (inclusive)
Close Window
X

Image Grid Parameters: SINC


Description

This defines the sample increment when drawing the grid, starting at BASESAMPLE. The sample increment is the spacing between samples.

Type integer
Default 100
Minimum 1 (inclusive)
Close Window
X

Ground Grid Parameters: BASELAT


Description

This is the latitude on which LATINC is mathematically based. This establishes a starting point for a global 'virtual' grid where latitude lines are drawn where the input image intersects the virtual grid. The application assumes user input reflects proper units (e.g. planetographic, planetocentric latitude) as defined within the image.

Type double
Default 0.0
Minimum -90.0 (inclusive)
Close Window
X

Ground Grid Parameters: BASELON


Description

This is the longitude on which LONINC is mathematically based. This establishes a starting point for a global 'virtual' grid where longitude lines are drawn where the input image intersects the virtual grid.

Type double
Default 0.0
Minimum -360.0 (inclusive)
Close Window
X

Ground Grid Parameters: LATINC


Description

This defines the latitude increment, based on BASELAT, on which grid lines are drawn. This establishes a global 'virtual' grid where latitude lines are drawn only where the input image intersects the virtual grid.

Type double
Default 10.0
Minimum 0.0 (inclusive)
Close Window
X

Ground Grid Parameters: LONINC


Description

This defines the longitude increment, based on BASELON, on which grid lines are drawn. This establishes a global 'virtual' grid where longitude lines are drawn only where the input image intersects the virtual grid.

Type double
Default 10.0
Minimum 0.0 (inclusive)
Close Window
X

Ground Grid Limits: MINLAT


Description

This defines the minimum latitude to which longitude grid lines will extend. If BOUNDARY is selected, a latitude line will be drawn at this latitude.

Type double
Internal Default Automatic
Minimum -90 (inclusive)
Maximum 90 (inclusive)
Close Window
X

Ground Grid Limits: MAXLAT


Description

This defines the maximum latitude to which longitude grid lines will extend. If BOUNDARY is selected, a latitude line will be drawn at this latitude.

Type double
Internal Default Automatic
Minimum -90 (inclusive)
Maximum 90 (inclusive)
Greater Than MINLAT
Close Window
X

Ground Grid Limits: MINLON


Description

This defines the minimum longitude to which latitude grid lines will extend. If BOUNDARY is selected, a longitude line will be drawn at this longitude.

Type double
Internal Default Automatic
Minimum -360 (inclusive)
Maximum 360 (inclusive)
Close Window
X

Ground Grid Limits: MAXLON


Description

This defines the maximum longitude to which latitude grid lines will extend. If BOUNDARY is selected, a longitude line will be drawn at this longitude.

Type double
Internal Default Automatic
Minimum -360 (inclusive)
Maximum 360 (inclusive)
Greater Than MINLON
Close Window
X

Line Parameters: LINEWIDTH


Description

This defines the thickness of grid lines in pixels.

Type integer
Default 1
Minimum 1 (inclusive)
Odd This value must be an odd number
Close Window
X

Line Parameters: LINEVALUE


Description

With this option choose DN, LRS, HRS, or NULL to define how to assign the grid line value. Use DNVALUE parameter to assign a number if DN option is chosen.

Type string
Default HRS
Option List:
Option Brief Description
HRSUse HRS DN value Use the special pixel value HRS (High Representation Saturation) as the grid line value. This may vary with bit type used.

Exclusions

  • DNVALUE
LRSUse LRS DN value Use the special pixel value LRS (Low Representation Saturation) as the grid line value. This may vary with bit type used.

Exclusions

  • DNVALUE
NULLUse NULL DN value Use the special pixel value NULL as the grid line value. This may vary with bit type used.

Exclusions

  • DNVALUE
DNUse given DN value Use the DN value specified in the DNVALUE parameter. It is recommended to run the stats application on the cube before selecting a DN value.
Close Window
X

Line Parameters: DNVALUE


Description

This is the DN value to be used as the value of the grid lines when LINEVALUE=DN. It is beneficial to first run the stats application to determine image minimum and maximum values.

Type double
Close Window
X

Background Type: BKGNDVALUE


Description

This option allows for any DN value, HRS, LRS, or NULL special pixel values to be chosen as the background value.

Type string
Default IMAGE
Option List:
Option Brief Description
IMAGEUse the input cube value Use the input cube pixel value as the background value. This will superimpose the grid on top of the input image.

Exclusions

  • BKGNDDNVALUE
HRSUse HRS DN value Use the special pixel value HRS (High Representation Saturation) as the background value. This may vary with bit type used.

Exclusions

  • BKGNDDNVALUE
LRSUse LRS DN value Use the special pixel value LRS (Low Representation Saturation) as the background value. This may vary with bit type used.

Exclusions

  • BKGNDDNVALUE
NULLUse NULL DN value Use the special pixel value NULL as the background value. This may vary with bit type used.

Exclusions

  • BKGNDDNVALUE
DNUse given DN value Use the DN value specified in the BKGNDDNVALUE parameter. It is recommended to run the stats application on the cube before selecting a DN value.

Inclusions

  • BKGNDDNVALUE
Close Window
X

Background Type: BKGNDDNVALUE


Description

This is the DN value to be used as the value of the background when BKGNDVALUE=DN. It may be beneficial to first run the stats application to determine image minimum and maximum values.

Type double
Close Window
X

Tick Parameters: DIAGONALTICKS


Description

Draw tick marks diagonally (creating an 'x'), instead of default vertical/horizontal ('+')

Type boolean
Default false
Close Window
X

Tick Parameters: TICKSIZE


Description

This defines the width and height (which are always equal) of the tick marks in pixels.

Type integer
Default 5
Minimum 1 (inclusive)
Odd This value must be an odd number
Close Window

Example 1

Basic latitude/longitude graticule

Description

In this example, the latitude and longitude grid lines are drawn every 10 degrees starting at 0.0 degree latitude and longitude.

Command Line

grid from=aeolis_reduced.cub to=grid_ex1.cub
Superimpose grid lines using default settings.

GUI Screenshot

Grid GUI

Example GUI

Screenshot of GUI with default parameters.

Input Image

Input image

Input file

Parameter Name: From

This is the ungridded input image.

Output Image

Gridded output image

Gridded output file

Parameter Name: TO

This file is gridded every 10 degrees in latitude and longitude starting at 0.0 degree latitude and longitude.


Example 2

Simple rectangular grid

Description

In this example, the grid lines are drawn based on the line and sample coordinates entered by the user in IMAGE mode.

Command Line

grid from=aeolis_reduced.cub to=grid_ex2.cub mode=image baseline=23 basesamp=17 sinc=30 linc=40
Superimpose grid lines using line and sample coordinates.

GUI Screenshot

Grid GUI

Example GUI

Screenshot of GUI with parameter settings defined by the user.

Input Image

Input image

Input file

Parameter Name: From

This is the ungridded input image.

Output Image

Gridded output image

Output file

Parameter Name: TO

The grid lines intersect at line 23 and sample 17, with vertical lines drawn every 30 pixels and horizontal lines every 40 pixels outward from the origin.


Example 3

Insert a graticule within the input image

Description

In this example, the grid lines are drawn based on a set of user-defined values for the different latitude and longitude parameters. The graticule is drawn only within the minimum and maximum latitude and longitude extents entered by the user.

Command Line

grid from=aeolis_reduced.cub to=grid_ex4.cub mode=ground baselat=0 baselon=0 latinc=2.5 loninc=2.5 minlat=-8 maxlat=-1 minlon=140 maxlon=145 bound=yes
Superimpose grid lines using 2.5 degrees latitude and longitude increments from an origin (0,0) defined by the user. The outer edges of the graticule bounding box will be gridded (BOUND=YES).

GUI Screenshot

Grid GUI

Example GUI

Screenshot of GUI with parameter settings defined by the user.

Input Image

Input image

Input file

Parameter Name: From

This is the ungridded input image.

Output Images

Gridded output image using BOUND=YES

Output file

Parameter Name: TO

The grid lines intersect at 0.0 degree latitude and longitude, and increments every 2.5 degrees in latitude and longitude. The outer edges of the bounding box around the minimum and maximum extents are gridded (BOUND=YES).

Gridded output image using BOUND=NO

Second output file using BOUND=NO

Parameter Name: TO

The grid lines intersect at 0.0 degree latitude and longitude, and increments every 2.5 degrees in latitude and longitude. The outer edges of the bounding box are not gridded (BOUND=NO).

Command line:
grid from=aeolis_reduced.cub to=grid_ex4b.cub mode=ground baselat=0 baselon=0 latinc=2.5 loninc=2.5 minlat=-8 maxlat=-1 minlon=140 maxlon=145 bound=no