ISIS Application Documentation

stretch

Printer Friendly View | TOC | Home

Remaps pixel values in a cube

Overview

Parameters

Example 1

Example 2

Example 3

Example 4

Example 5

Description

This program stretchs or remaps pixels values in a cube. Note that the same stretch is applied to all bands within the cube. The underlying method for remapping pixels is defined by a set of stretch pairs and is best described using an example:

      0:0
      255:1

A stretch pair is two numbers separated by a colon. In this case, 0:0 and 255:1 comprise two stretch pairs. A pair is used to identify the mapping of input pixels to output pixels where the colon is a delimiter (i.e., input:output). Our first pair indicates input pixel values of 0 will be mapped to an output 0, while the second pair indicates input pixel values of 255 will be mapped to 1. All inputs between 0 and 255 will be mapped linearly (e.g., 127.5 will be mapped to 0.5). Therefore, the output cube will only have pixel values between 0 and 1. Those input pixels below 0 will be mapped to LRS and above 255 to HRS. This mapping to special pixels can be overridden. Because multiple pairs are allowed, many different types of remappings can be accomplished. For example:

      Inverse Stretch
      0:255
      255:0

      Piece-wise Linear Stretch
      20:0.0
      50:0.5
      125:1.0

      Saw-tooth Stretch
      0:0.0
      50:1.0
      100:0.0
      200:1.0

      Binary stretch
      0:0.0
      49.9999:0.0
      50:1.0.0
      79.9999:1.0
      80:0.0
      255:0.0

If you are having difficulty visualizing these stretches simply plot the input:output pairs on graph paper and connect the dots or see some of the examples. Note that the input value of each pair is in ascending order. As a reminder, all input pixel values less than the input value for the first pair are mapped to LRS. Likewise, all pixel values greater than the input value for the last pair are mapped to HRS.

History

Jim Torson	1990-11-17	Original version
Jeff Anderson	2002-09-17	Ported to Isis 3.0
K Teal Thompson	2002-12-03	Add examples
K Teal Thompson	2003-04-04	Make images smaller. Adjust binary stretch example.
Kim Sides	2003-05-13	Added application test
Stuart Sides	2003-05-16	Modified schema location from astogeology... to isis.astrogeology..."
Stuart Sides	2003-05-30	Made changes to application test truth files to reflect -O1 optimization
Stuart Sides	2003-07-29	Modified filename parameters to be cube parameters where necessary
Brendan George	2006-06-30	Fixed application test
Jeannie Walldren	2008-01-09	Modified stretch parameters (except PAIRS) to accept string instead of double so that special pixels may be set to other special pixel values.
Eric Hyer	2009-04-30	Users can pass a file containing stretch pairs as well as inputing them manually as before. Also, the input side of stretch pairs can optionally be percentages instead of dn values.
Eric Hyer	2010-04-23	Added support for stretch files not ending in a newline. Also did some code refactoring to eliminate duplicate code.

U.S. Department of the Interior | U.S. Geological Survey
ISIS | Privacy & Disclaimers | Astrogeology Research Program
To contact us, please post comments and questions on the USGS Astrogeology Discussion Board
To report a bug, or suggest a feature go to: ISIS Github
File Modified: 02/21/2025 19:28:14

Parameter Groups

Files

Name	Description
FROM	Input cube
TO	Output stretched cube

Stretch Parameters

Name	Description
USEPERCENTAGES	Percentage mode for pairs
READFILE	Input pairs from file
PAIRS	Stretch pairs manual input
INPUTFILE	The file name where pairs are stored
NULL	Replace NULL pixels with another special pixel value or a double value
LIS	Replace LIS pixels with another special pixel value or a double value
LRS	Replace LRS pixels with another special pixel value or a double value
HIS	Replace HIS pixels with another special pixel value or a double value
HRS	Replace HRS pixels with another special pixel value or a double value

Files: FROM

Description

Input cube to stretch

Type	cube
File Mode	input
Filter	*.cub

Close Window

Files: TO

Description

The resultant stretched cube

Type	cube
File Mode	output
Pixel Type	real

Close Window

Stretch Parameters: USEPERCENTAGES

Description

If true the input side of the pairs are interpreted as percentages. The dn value which is used is the dn value at the specified percentage of the input cube's histogram

Type	boolean
Default	False

Close Window

Stretch Parameters: READFILE

Description

Selects the method of pair data input. If true then read pairs from a file. Otherwise read the stretch pairs from the "PAIRS" parameter

Type	boolean
Default	False
Exclusions	PAIRS
Inclusions	INPUTFILE

Close Window

Stretch Parameters: PAIRS

Description

A string must be entered in the form of Where the input values are in ascending order (increasing). There is no limit to the number of pairs although each pair must be separated by a space. The stretch that is entered will be applied to all bands in the cube. By default "No Stretch" is applied which allows users to remap only special pixels if desired.

Type	string
Internal Default	No Stretch

Close Window

Stretch Parameters: INPUTFILE

Description

Read pairs from this file instead of entering them manually. Commented lines are ignored and defined as beginning with a '#'. Pairs must be separated by white space which may be new lines.

            # example 1 of a file containing stretch pairs
            0:0 1:10 15:255

            # example 2 of a file containing stretch pairs
            0:0
            1:10
            # this is a comment inside a file containing stretch pairs
            15:255

Type	filename
File Mode	input

Close Window

Stretch Parameters: NULL

Description

Double or alternate special pixel value used to replace all NULL special pixels. For example all NULL pixels can be replaced with -100.0. By default, the NULL special pixels will be left unchanged.

Type	string
Internal Default	NULL

Close Window

Stretch Parameters: LIS

Description

Double or alternate special pixel value used to replace all LIS special pixels. For example all LIS pixels can be replaced with 0.0. By default, the LIS special pixels will be left unchanged.

Type	string
Internal Default	LIS

Close Window

Stretch Parameters: LRS

Description

Double or alternate special pixel value used to replace all LRS special pixels. For example all LRS pixels can be replaced with 0.0. By default, the LRS special pixels will be left unchanged.

Type	string
Internal Default	LRS

Close Window

Stretch Parameters: HIS

Description

Double or alternate special pixel value used to replace all HIS special pixels. For example all HIS pixels can be replaced with 500.0. By default, the HIS special pixels will be left unchanged.

Type	string
Internal Default	HIS

Close Window

Stretch Parameters: HRS

Description

Double or alternate special pixel value used to replace all HRS special pixels. For example all HRS pixels can be replaced with 500.0. By default, the HRS special pixels will be left unchanged.

Type	string
Internal Default	HRS

Close Window

Example 1

run stretch

Description

This example shows a stretch operation using a binary type of stretch.

Command Line

stretch f=../IN/peaks.cub:4 t=OUT/stretchBin p=\"0.:0 101.9:0 102.:255 200.:255 200.1:0. 255.:0.\"

stretch a Terra image. Use binary type of stretch.

GUI Screenshot

stretch Gui

Example Gui

Screenshot of GUI with parameters filled in to perform a stretch operation on the input image.

Input Images

Input image

Input image for stretch

Parameter Name: FROM

This is the input image for the stretch examples.

graph demonstration

Explanation image for stretch

This is a graph demonstrating the binary stretch.

Output Image

Output image showing results of the stretch application.

Output image for stretch

Parameter Name: TO

This is the output image that results from a binary type of stretch

Example 2

run stretch

Description

This example shows the result of stretching dark data.

Command Line

stretch f=../IN/peaks.cub:4 t=OUT/stretchDark p=\"0.:0 50.:255 255.:255.\"

stretch the dark data in a Terra image.

GUI Screenshot

stretch Gui

Example Gui

Screenshot of GUI with parameters filled in to perform a stretch operation on the input image.

Input Images

Input image

Input image for stretch

Parameter Name: FROM

This is the input image for the stretch examples.

graph demonstration

Explanation image for stretch

This is a graph demonstrating dark data enhancement.

Output Image

Output image showing results of the stretch application.

Output image for stretch

Parameter Name: TO

This is the output image that results from a dark data enhancement

Example 3

run stretch

Description

This example shows the result of stretching light data.

Command Line

stretch f=../IN/peaks.cub:4 t=OUT/stretchLight p=\"0.:0 84.:0 255.:255.\"

stretch the light data in a Terra image.

GUI Screenshot

stretch Gui

Example Gui

Screenshot of GUI with parameters filled in to perform a stretch operation on the input image.

Input Images

Input image

Input image for stretch

Parameter Name: FROM

This is the input image for the stretch examples.

graph demonstration

Explanation image for stretch

This is a graph demonstrating light data enhancement.

Output Image

Output image showing results of the stretch application.

Output image for stretch

Parameter Name: TO

This is the output image that results from a light data enhancement

Example 4

run stretch

Description

This example shows a stretch operation using a inverse type of stretch.

Command Line

stretch f=../IN/peaks.cub:4 t=OUT/stretchInv p=\"0.:255 255.:0.\"

stretch a Terra image. Use inverse type of stretch.

GUI Screenshot

stretch Gui

Example Gui

Screenshot of GUI with parameters filled in to perform an inverse stretch operation on the input image.

Input Images

Input image

Input image for stretch

Parameter Name: FROM

This is the input image for the stretch examples.

graph demonstration

Explanation image for stretch

This is a graph demonstrating the inverse stretch.

Output Image

Output image showing results of the stretch application.

Output image for stretch

Parameter Name: TO

This is the output image that results from an inverse type of stretch

Example 5

run stretch

Description

This example shows how to input non-double parameters for the special pixel values.

Command Line

stretch f=peaks.cub:4 t=stretch NULL=lis Lis=LR Lr=hi his=Hr Hr=n

stretch a Terra image. Input non-double parameters.

GUI Screenshot

stretch Gui

Example Gui

Screenshot of GUI with non-double values filled in to the special pixel parameters.

Input Image

Input image

Input image for stretch

Parameter Name: FROM

This is the input image for the stretch examples.

Output Image

Output image showing results of the stretch application.

Output image for stretch

Parameter Name: TO

This is the output image that results from swapping special pixel values. Notice that there is no visible change since all special pixel values have the same value.

Quick Links

Documentation Versions

stretch

Description

Categories

Related Objects and Documents

Applications

History

Parameter Groups

Files

Stretch Parameters

Files: FROM

Description

Files: TO

Description

Stretch Parameters: USEPERCENTAGES

Description

Stretch Parameters: READFILE

Description

Stretch Parameters: PAIRS

Description

Stretch Parameters: INPUTFILE

Description

Stretch Parameters: NULL

Description

Stretch Parameters: LIS

Description

Stretch Parameters: LRS

Description

Stretch Parameters: HIS

Description

Stretch Parameters: HRS

Description

Example 1

Description

Command Line

GUI Screenshot

Input Images

Output Image

Example 2

Description

Command Line

GUI Screenshot

Input Images

Output Image

Example 3

Description

Command Line

GUI Screenshot

Input Images

Output Image

Example 4

Description

Command Line

GUI Screenshot

Input Images

Output Image

Example 5

Description

Command Line

GUI Screenshot

Input Image

Output Image