ISIS Application Documentation
barscale | Standard View | TOC | Home |
Creates a bar scale for an image
Description
Categories
Groups
History
The barscale program creates a horizontal bar scale for a given image.
The bar scale is a bar graphic divided into portions and labeled with a unit measurement associated with corresponding ground length. It indicates, for example, the scale of an image or map. Many users find bar scales helpful to place on maps and images for publication so that observers can make a quick assessment of distance relationships.
How Barscale Works
This program uses the USGS standard as a guide for producing the bar scale. The USGS standard can be viewed at http://pubs.usgs.gov/of/1999/of99-430/of99-430_sec35.pdf. The program takes a projected or unprojected image file as input. If the image is unprojected, it must be initialized with SPICE information. This can be achieved by running the spiceinit program on the unprojected file. The pixel resolution (PIXRES) is obtained either from the CENTER or from a user defined location in the image file (USERLOC). The user determines the desired length of the bar scale and the unit of measurement, either METER or KILOMETER, to employ. The length of the bar scale is controlled using the LEFTLIMIT, LEFTSEGS, RIGHTLIMIT, and RIGHTSEGS parameters. The right side of a bar scale is used to provide larger divisions of measurement and the left side provides smaller divisions of measurement but is not required. The examples below are provided to demonstrate how these parameters are used.
Example 1: To create a bar scale with no left limit and a right limit of 20 kilometers with 4 divisions: LEFTLIMIT=0 LEFTSEGS=0 RIGHTLIMIT=20 RIGHTSEGS=4 UNIT=KILOMETER
Example 2: To create a bar scale with a left limit of 10 kilometers with 5 divisions and a right limit of 20 kilometers with 2 divisions: LEFTLIMIT=10 LEFTSEGS=5 RIGHTLIMIT=20 RIGHTSEGS=2 UNIT=KILOMETER
Important Facts to Remember
How to Place the Bar Scale in the Image File:
There are two options for placing the bar scale in the image file.
1) Set the PADIMAGE option to false if the bar scale should be placed on the image at a specified line and sample. The CORNERLINE and CORNERSAMPLE parameters need to be set to the upper left corner at the bar scale's insertion point.
2) Set the PADIMAGE option to true if the bar scale should be appended to the bottom of the image file. The bar scale will be justified LEFT, CENTER, or RIGHT within the padding depending on the user's choice.
Please note that this program is designed to generate bar scales for localized images. This program should not be used to generate a bar scale for a global image because of the drastic resolution changes that occur across the expanse of a global image.
Name | Description |
---|---|
FROM | Input cube file |
TO | Output cube file |
Name | Description |
---|---|
PIXRES | Specifies the location to calculate pixel resolution |
LINE | Line in image to calculate resolution |
SAMPLE | Sample in image to calculate resolution |
UNITS | Specifies the units of measurement to use for scale |
LEFTLIMIT | Size of left side of scale in UNITS specified |
LEFTSEGS | Number of segments in left side of scale |
RIGHTLIMIT | Size of right side of scale in UNITS specified |
RIGHTSEGS | Number of segments in right side of scale |
CORNERLINE | Line location of upper left corner of scale in image |
CORNERSAMPLE | Sample location of upper left corner of scale in image |
BARHEIGHT | Height of bar scale in pixels |
BACKGROUND | Specifies the background color to use for the scale |
TEXTHEIGHT | Bar scale text height in pixels |
TEXTLOC | Specifies the location of text in relation to the bar scale |
PADIMAGE | Add padding at bottom of image to hold bar scale |
PLACEMENT | Specifies how to place the bar scale in the padding of the image |
This is the input image cube that the bar scale will be created for.
Type | cube |
---|---|
File Mode | input |
Filter | *.cub |
This is the output file name. The cube file will contain the bar scale.
Type | cube |
---|---|
File Mode | output |
Specifies the location in the image where the pixel resolution will be calculated: the center of the image or a user-defined line and sample in the image.
Type | string | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
Default | CENTER | |||||||||
Option List: |
|
This is the line number in the input image where the pixel resolution will be calculated at.
Type | double |
---|
This is the sample number in the input image where the pixel resolution will be calculated at.
Type | double |
---|
Specifies the units of measurement to use for the bar scale. Must be METER or KILOMETER.
Type | string | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
Default | KILOMETER | |||||||||
Option List: |
|
If this value is greater than zero, then there will be a left hand side to the scale and the LEFTLIMIT will be the limit in UNITS of that side of the scale.
Type | integer |
---|---|
Default | 0 |
Minimum | 0 (inclusive) |
This is the number of segments that the left side of the scale will be divided into.
Type | integer |
---|---|
Internal Default | None |
Minimum | 1 (inclusive) |
This value must be greater than zero. It is the limit in UNITS of the right side of the scale.
Type | integer |
---|---|
Default | 1 |
Minimum | 0 (exclusive) |
This is the number of segments that the right side of the scale will be divided into.
Type | integer |
---|---|
Default | 1 |
Minimum | 1 (inclusive) |
This is the line in the input image file where the upper left corner of the bar scale will be placed.
Type | integer |
---|---|
Internal Default | None |
This is the sample in the input image file where the upper left corner of the bar scale will be placed.
Type | integer |
---|---|
Internal Default | None |
This is the number of pixels that will be used in the vertical dimension of the bar scale. This value has to be at least 5 to create a bar scale.
Type | integer |
---|---|
Default | 50 |
Minimum | 5 (inclusive) |
Specifies the background color to user for the scale bar. If the background is black, then the lines and text will be white. If the background is white, then the lines and text will be black.
Type | string | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
Default | WHITE | |||||||||
Option List: |
|
This is the height in pixels of the text that will be written above/below the bar scale.
Type | integer |
---|---|
Default | 50 |
Minimum | 10 (inclusive) |
Specifies the location of the text in relation to the bar scale. The text can be printed either above or below the bar scale.
Type | string | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
Default | ABOVE | |||||||||
Option List: |
|
Determines if the bar scale will be written directly on the image file at the line,sample specified, or if the bar scale will be written and appended to the bottom of the image file. The user will still need to specify the upper left sample of the bar scale.
Type | boolean |
---|---|
Default | FALSE |
Exclusions |
|
Inclusions |
|
This determines how the bar scale will be placed in the padding that is added to the image. The three options are LEFT justified, CENTER, or RIGHT justified.
Type | string | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Default | LEFT | ||||||||||||
Option List: |
|
Janet Barrett | 2013-01-22 | Original version. |
Janet Richie | 2013-02-22 | Documentation review. |
Janet Barrett | 2013-03-07 | Updated code to meet standards. References #575. |