User's Guide

SARTOPO

Calculate radar viewing angles and range vectors

Function:

Calculates the incidence angle, radar look angle and/or the range vectors for each pixel of the input elevation data. Two subcommands are available. -LINE calculates the above information based on a user defined flight path. -POINT calculates the above information based on a stationary point along a flight path. In addition to the above information, -POINT and -LINE allows calculation of the azimuth angle.

Parameters:

Subcommand -POINT:
Base calculations on the location of the platform at a single point in time. Calculations of all angles and range vectors are based on a stationary point along a flight path.

IN
Input image. The single band input image consisting of elevation data. Its data type may be either BYTE, INTEGER*2, INTEGER*4 or REAL*4. Window and/or band options may be specified. The elevation data is assumed to be in meters.

LAT
Latitude. Latitude of the point from which all calculations will be made. The latitude value is entered as degrees, minutes and seconds. South latitude values must be entered as negative degrees.

LONG
Longitude. Longitude of the point from which all calculations will be made. The longitude value is entered as degrees, minutes and seconds. West longitude values must be entered as negative degrees.

ELEV
Elevation. The elevation in meters of the aircraft or spacecraft platform. This value is assumed to be constant along the flight path.

OUT
Output image. The number of bands contained in the output image is based on the parameter CALCOPT. One band is created in the output image for each value set. If the output data type selected for the image is not REAL, values are rounded and truncated. The output image specifies angles in decimal degrees and range vectors in meters.

CALCOPT(INCID,LOOK,AZM,RANGE)
Calculation option. The list of options indicating the information to be calculated for each pixel of the input image. From one to four values may be entered for CALCOPT.

  = INCID: Incidence angle.  The angle defined by the
	   surface normal vector of the current pixel 
	   of the input image and the range vector.  
  = LOOK:  Radar look angle.  The angle defined by a
	   vector at a right angle to the current
	   platform velocity vector and the range vector. 
  = AZM:   Azimuth angle.  The azimuth angle from the
	   aircraft or spacecraft plane.
  = RANGE: Range vector.  Distance in meters from the
	   input pixel to the platform along the range 
	   vector.

OFFSET(0)
Offset value (in meters). OFFSET will be subtracted from each range vector calculation. This can be useful if the range vector values are very large (e.g. for a spacecraft platform).

ODTYPE(R*4)
Output data type. The data type of the output image. Specification of BYTE, I*2 and I*4 causes the rounding and truncation of data. Therefore, these data types should be used with caution since all calculations for SARTOPO are floating point calculations.

  = BYTE:  BYTE      (8-bit unsigned integer)
                     (0 through 255)
  = I*2:   INTEGER*2 (16-bit signed integer)
                     (-32768 through 32767)
  = I*4:   INTEGER*4 (32-bit signed integer)
                     (-2147483648 through 2147483647)
  = R*4:   REAL*4    (32-bit signed real)
                     (System dependent)
Subcommand -LINE:
Base calculations on a user defined flight path. Calculations of angles and range vectors are based on the user defined aircraft or spacecraft flight path. For each pixel, the current position along the defined flight path of the aircraft or spacecraft is calculated.

IN
Input image. The single band input image consisting of elevation data. Its data type may be either BYTE, INTEGER*2, INTEGER*4 or REAL*4. Window and/or band options may be specified. The elevation data is assumed to be in meters.

BEGLAT
Beginning latitude. The latitude value marking the starting point of the flight path of the aircraft or spacecraft platform. The latitude value is entered as degrees, minutes and seconds. South latitude values must be entered as negative degrees.

BEGLONG
Beginning longitude. The longitude value marking the starting point of the flight path of the aircraft or spacecraft platform. The longitude value is entered as degrees, minutes and seconds. West longitude values must be entered as negative degrees.

ENDLAT
Ending latitude. The latitude value marking the ending point of the flight path of the aircraft or spacecraft platform. The latitude value is entered as degrees, minutes and seconds. South latitude values must be entered as negative degrees.

ENDLONG
Ending longitude. The longitude value marking the ending point of the flight path of the aircraft or spacecraft platform. The longitude value is entered as degrees, minutes and seconds. West longitude values must be entered as negative degrees.

ELEV
Elevation. The elevation in meters of the aircraft or spacecraft platform. This value is assumed to be constant along the flight path.

OUT
Output image. The number of bands contained in the output image is based on the parameter CALCOPT. One band is created in the output image for each value set. If the output data type selected for the image is not REAL, values are rounded and truncated. The output image specifies angles in decimal degrees and range vectors in meters.

CALCOPT(INCID,LOOK,AZM,RANGE)
Calculation option. The list of options indicating the information to be calculated for each pixel of the input image. From one to four values may be entered for CALCOPT.

  = INCID: Incidence angle.  The angle defined by the
	   surface normal vector of the current pixel 
	   of the input image and the range vector.  
  = LOOK:  Radar look angle.  The angle defined by a
	   vector at a right angle to the current
	   platform velocity vector and the range vector. 
  = AZM:   Azimuth angle.  The azimuth angle from the
	   aircraft or spacecraft plane.
  = RANGE: Range vector.  Distance in meters from the
	   input pixel to the platform along the range 
	   vector.

OFFSET(0)
Offset value (in meters). OFFSET will be subtracted from each range vector calculation. This can be useful if the range vector values are very large (e.g. for a spacecraft platform).

ODTYPE(R*4)
Output data type. The data type of the output image. Specification of BYTE, I*2 and I*4 causes the rounding and truncation of data. Therefore, these data types should be used with caution since all calculations for SARTOPO are floating point calculations.

  = BYTE:  BYTE      (8-bit unsigned integer)
                     (0 through 255)
  = I*2:   INTEGER*2 (16-bit signed integer)
                     (-32768 through 32767)
  = I*4:   INTEGER*4 (32-bit signed integer)
                     (-2147483648 through 2147483647)
  = R*4:   REAL*4    (32-bit signed real)
                     (System dependent)

Examples:

  1. LAS> sartopo-line in=elev beglat=(39 32 13) beglong=(-113 7 23) endlat=(39 37 23) endlong=(-113 0 4) elev=5000 out=radar

    In this example, the user has input the beginning and ending latitudes and longitudes of the flight path. The elevation value entered is assumed to be in meters and is assumed to be constant over the flight path. The output REAL*4 image created by SARTOPO will contain 3 bands. The first band will contain the incidence angles (in decimal degrees), the second band will contain the radar look angles (also in decimal degrees), the third band will contain the azimuth angles (in decimal degrees) and the fourth band will contain the lengths (in meters) of the range vectors.

  2. LAS> sartopo-line in=elev beglat=(39 30 0) beglong=(-113 10 0) endlat=(39 40 0) endlong=(-113 0 0) elev=6000 out=radar calcopt=(range) offset=5000

    In this example, the user has input the beginning and ending latitudes and longitudes of the flight path. The elevation value entered is assumed to be in meters and is assumed to be constant over the flight path. The output REAL*4 image created by SARTOPO will contain a single band. This band will contain the lengths (in meters) of the range vectors. The OFFSET value of 5000 will subtracted from each output value.

  3. LAS> sartopo-point in=dem lat=(39 32 13) long=(-113 0 4) elev=6000 out=sarangle odtype=i*2

    In this example, the user has input the latitude and longitude of a stationary point from which all subsequent calculations are made. The elevation value entered is assumed to be in meters. The output INTEGER*2 image created by SARTOPO will contain 4 bands. The first band will contain the incidence angles (in decimal degrees), the second band will contain the radar look angles (in decimal degrees), the third band will contain the azimuth angles (in decimal degrees) and the fourth band will contain the lengths (in meters) of the range vectors.

Description/Algorithm:

SARTOPO is used to calculate radar viewing angles as well as range vectors using the input elevation image. For each pixel of the input image, the user may choose to have the inicidence angle, the radar look angle and/or the range vector calculated. If either subcommand is chosen, the azimuth angle may also be calculated. All information for the point mode is calculated from a stationary point along the flight path which is input by the user as a latitude/longitude value. If the subcommand -LINE is chosen, the position along the user input flight path which is the shortest distance from which the current pixel can be seen is calculated. The viewing angles and range vectors are then calculated from this position. The range vector calculation is actually the length of the vector whose end points are the current pixel location and the aircraft/spacecraft position. The parameter OFFSET can be used to scale this value. This is especially useful if calculations are being made for a spacecraft platform since these values can become quite large. The incidence angle is the angle defined by the range vector and the surface normal vector of the current pixel. The normal vector of the current pixel (a vector perpendicular to the current pixel) is the average of 4 normal vectors calculated using 4 points surrounding the current pixel. The radar look angle is the angle defined by the perpendicular to the flight path plane (aircraft) or the orbital plane (spacecraft) and the range vector. The azimuth angle is measured from the north pole and is calculated based on the user input position and the current pixel location.

Nonfatal Error Messages:

  1. [sartopo-warn] Nonfatal error encountered

    A nonfatal error was encountered during processing. The image data is probably valid and therefore saved. The error message that is displayed immediately preceding this message is the specific error that was encountered. Processing continues.

Fatal Error Messages:

  1. [sartopo-fatal] Fatal error encountered

    A fatal error was encountered during processing. The error message that is displayed immediately preceding this message is the specific error that was encountered.

  2. [sartopo-maxbnd] Maximum number of input bands exceeded

    SARTOPO works with elevation data. Therefore, only 1 band of image data is allowed. Enter either a single band image or use the band specification syntax to select 1 band from a multi-band image for the IN parameter.

  3. [sartopo-alloc] Error allocating dynamic memory

    An error was encountered while attempting to dynamically allocate memory. The user may have reached the memory limits of the system. Contact the system manager for more information.

User Notes:

  1. All input image data is assumed to be in meters. If the input image units are not meters (eg. feet), the user must convert the image values to meters prior to running SARTOPO.

  2. Although all data types are allowed for the output image, REAL*4 will give the most accurate results. Since three of the four possible output bands contain angles in decimal degrees, a large amount of information may be lost by specifying an output data type of BYTE, INTEGER*2 or INTEGER*4.