ISIS Application Documentation
Creates a bar scale for an image
Description
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
-
Ensure that the bar scale limits are set to a reasonable size based on the resolution of the
image. If the limits are set too small, the bar scale will not be useful. For example, if an
image has a resolution of 153 meters/pixel, then the result of setting the limit to 10 times
greater than the resolution will produce a bar scale that is only 10 pixels wide; this may or
may not be considered a useful bar scale.
-
The vertical height (in pixels) of the bar scale must be provided along with the font size
(in pixels).
-
The width of the bar scale is dependent upon the resolution of the image and the RIGHTLIMIT
and LEFTLIMIT set by the user. It should be noted that the TEXTHEIGHT provided by the user
to specify font height does not mean that the characters will be exactly that number of pixels
tall. The height of the text will only be about 75% of what is specified. This is because of
the way that fonts are defined. Each font has a certain number of pixels devoted to the ascent
above its baseline and to the descent below its baseline. Keep this in mind when specifying
the height of the text for the bar scale.
-
The BACKGROUND of the bar scale can be set to either BLACK or WHITE.
-
The text that goes with the bar scale can either go ABOVE the bar scale or BELOW it.
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.
Categories
History
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.
|
|
Parameter Groups
Files
Name
|
Description
|
FROM |
Input cube file
|
TO |
Output cube file
|
Bar Scale Options
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 |
|
Files:
FROM
Description
This is the input image cube that the bar scale will be created
for.
Type
| cube |
File Mode
| input |
Filter
|
*.cub
|
Files:
TO
Description
This is the output file name. The cube file will contain the bar
scale.
Type
| cube |
File Mode
| output |
Bar Scale Options:
PIXRES
Description
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:
|
Option |
Brief |
Description |
CENTER | Get the pixel resolution from the center of the image |
The pixel resolution will be obtained from the center line and
sample of the image.
Exclusions
|
USER | Get the pixel resolution from a user defined line and sample |
The pixel resolution will be obtained from a user defined line and
sample in the image file.
Inclusions
|
|
Bar Scale Options:
LINE
Description
This is the line number in the input image where the pixel
resolution will be calculated at.
Bar Scale Options:
SAMPLE
Description
This is the sample number in the input image where the pixel
resolution will be calculated at.
Bar Scale Options:
UNITS
Description
Specifies the units of measurement to use for the bar scale. Must
be METER or KILOMETER.
Type
| string |
Default
| KILOMETER |
Option List:
|
Option |
Brief |
Description |
KILOMETER | Bar scale unit of measurement |
The bar scale will be created using KILOMETER as its unit of
measurement.
|
METER | Bar scale unit of measurement |
The bar scale will be created using METER as its unit of
measurement.
|
|
Bar Scale Options:
LEFTLIMIT
Description
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)
|
Bar Scale Options:
LEFTSEGS
Description
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)
|
Bar Scale Options:
RIGHTLIMIT
Description
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)
|
Bar Scale Options:
RIGHTSEGS
Description
This is the number of segments that the right side of the
scale will be divided into.
Type
| integer |
Default
| 1 |
Minimum
| 1
(inclusive)
|
Bar Scale Options:
CORNERLINE
Description
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 |
Bar Scale Options:
CORNERSAMPLE
Description
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 |
Bar Scale Options:
BARHEIGHT
Description
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)
|
Bar Scale Options:
BACKGROUND
Description
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:
|
Option |
Brief |
Description |
BLACK | Bar scale background will be black |
The bar scale will be created using a background color of black.
All lines and text used to make the bar scale will be white.
|
WHITE | Bar scale background will be white |
The bar scale will be created using a background color of white.
All lines and text used to make the bar scale will be black.
|
|
Bar Scale Options:
TEXTHEIGHT
Description
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)
|
Bar Scale Options:
TEXTLOC
Description
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:
|
Option |
Brief |
Description |
ABOVE | Print text above the bar scale |
Print the text above the bar scale.
|
BELOW | Print text below the bar scale |
Print the text below the bar scale.
|
|
Bar Scale Options:
PADIMAGE
Description
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
|
|
Bar Scale Options:
PLACEMENT
Description
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:
|
Option |
Brief |
Description |
LEFT | Left justify the bar scale in the padding |
Left justify the bar scale in the padding at the bottom of the image. The
bar scale will be placed so that the leftmost part of the bar scale (including
text) is 10 pixels in from the left side of the image.
|
CENTER | Center the bar scale in the padding |
The bar scale will be placed in the padding at the bottom of the image so that the
center of the scale is at the center sample of the image
|
RIGHT | Right justify the bar scale in the padding |
Right justify the bar scale in the padding at the bottom of the image. The
bar scale will be placed so that the rightmost part of the bar scale (including
text) is 10 pixels in from the right side of the image.
|
|