HiRISE

HiRISE.HiPlan.SPICE
Class Geometry_Utilities

java.lang.Object
  extended by HiRISE.HiPlan.SPICE.Geometry_Utilities
All Implemented Interfaces:
SPICE_Constants

public class Geometry_Utilities
extends Object
implements SPICE_Constants

A utility class Mars-related geometry calculations. This class uses the NAIF SPICE toolkit via the ASU-developed JSPICE system.

Version:
1.6
Author:
Christian Schaller - UA/PIRL

Field Summary
static String ID
          Class identification name with source code version and date.
static double MARS_OBLIQUITY
          The obliquity of Mars in degrees.
static double SEARCH_MARGIN
          The default margin for the roll angle search, in seconds.
 
Fields inherited from interface HiRISE.HiPlan.SPICE.SPICE_Constants
AU, DEIMOS_ID, EARTH_ID, IAU_MARS_FRAME, J2000_FRAME, KM, KM_PER_AU, MARS_ID, MRO_HIGH_PRECISION_ID, MRO_ID, NO_ABCORR, PHOBOS_ID, SUN_ID
 
Method Summary
static double[] find_targeted_observation(double lon, double lat, double alt, double guess)
          Gets the observation time and roll angle for a targeted observation with the given initial guess at time and target coordinates.
static double[] find_targeted_observation(double lon, double lat, double alt, double guess, double beg, double end)
          Gets the observation time and roll angle for a targeted observation with the given initial guess at time, limits, and target coordinates.
static edu.asu.jmars.util.HVector[] intersect_planes(edu.asu.jmars.util.HVector n1, edu.asu.jmars.util.HVector p1, edu.asu.jmars.util.HVector n2, edu.asu.jmars.util.HVector p2)
          Derives the line that is the intersection of two planes.
static double mars_a_axis()
          Gets the A-axis for Mars.
static double mars_b_axis()
          Gets the B-axis for Mars.
static double mars_c_axis()
          Gets the C-axis for Mars.
static double mars_equatorial_radius()
          Gets the Mars equatorial radius.
static double mars_flattening()
          Gets the flattening coefficient for Mars.
static double mars_polar_radius()
          Gets the Mars polar radius.
static double normalize_longitude(double longitude)
          Returns the input longitude normalized to fall in the range (0.0, 360.0).
static double planetocentric_latitude(double planetographic_latitude)
          Converts a Mars planetographic latitude to planetocentric latitude.
static double planetographic_latitude(double planetocentric_latitude)
          Converts a Mars planetocentric latitude to planetographic latitude.
static Point2D point2d_degrees(Point2D point2d_radians)
          Converts a geographic point whose coordinates are in radians to one whose coordinates are in degrees.
static Point2D point2d_radians(Point2D point2d_degrees)
          Converts a geographic point whose coordinates are in degrees to one whose coordinates are in radians.
static double[] recgeo_ocentric(double[] rec)
          Converts a rectangular coordinate 3-vector to geographic coordinates in the east-leading planetocentric system.
static double[] recgeo_ographic(double[] rec)
          Converts a rectangular coordinate 3-vector to geographic coordinates in the east-leading planetographic system.
static double reverse_longitude(double longitude)
          Reverse a longitude from east-leading to west-leading or vice-versa.
static double solar_altitude(double target_longitude, double target_latitude, double et)
          Gets the solar altitide, or elevation, for a target located at the given coordinates at the given ephemeris time.
static double solar_altitude(double target_longitude, double target_latitude, double l_sub_s, double subsolar_longitude)
          Gets the solar altitide, or elevation, for a target located at the given coordinates and with the given solar geometry.
static double solar_azimuth(double target_longitude, double target_latitude, double et)
          Gets the solar azimuth angle for a target located at the given coordinates at the given ephemeris time.
static double solar_azimuth(double target_longitude, double target_latitude, double l_sub_s, double subsolar_longitude)
          Gets the solar azimuth angle for a target located at the given coordinates and with the given solar geometry.
static double solar_declination(double l_sub_s)
          Gets the solar declination for the given solar longitude.
static Point2D subsolar_point(double et)
          Gets the longitude and latitude coordinates of the sub-solar point on Mars at the given time.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ID

public static final String ID
Class identification name with source code version and date.

See Also:
Constant Field Values

MARS_OBLIQUITY

public static final double MARS_OBLIQUITY
The obliquity of Mars in degrees.

See Also:
Constant Field Values

SEARCH_MARGIN

public static final double SEARCH_MARGIN
The default margin for the roll angle search, in seconds.

See Also:
find_targeted_observation(double,double,double,double), Constant Field Values
Method Detail

mars_a_axis

public static double mars_a_axis()
Gets the A-axis for Mars. The A-axis is the larger equatorial radius.

Returns:
the Mars A-axis length in km.

mars_b_axis

public static double mars_b_axis()
Gets the B-axis for Mars. The B-axis is the smaller equatorial radius.

Returns:
the Mars B-axis length in km.

mars_c_axis

public static double mars_c_axis()
Gets the C-axis for Mars. The C-axis is the polar radius.

Returns:
the Mars C-axis length in km.

mars_equatorial_radius

public static double mars_equatorial_radius()
Gets the Mars equatorial radius. This radius is the length of the Mars A-axis.

Returns:
the Mars equatorial radius in km.

mars_polar_radius

public static double mars_polar_radius()
Gets the Mars polar radius. This radius is the length of the Mars C-axis.

Returns:
the Mars polar radius in km.

mars_flattening

public static double mars_flattening()
Gets the flattening coefficient for Mars. This coefficient is given by the following:
f = (re - rp) / re

where re is the equatorial radius and rp is the polar radius.

Returns:
the flattening coefficient for Mars.

planetocentric_latitude

public static double planetocentric_latitude(double planetographic_latitude)
Converts a Mars planetographic latitude to planetocentric latitude. The value for mars_flattening() is used in the conversion.

Parameters:
planetographic_latitude - the planetographic latitude in radians.
Returns:
the planetocentric latitude in radians.

planetographic_latitude

public static double planetographic_latitude(double planetocentric_latitude)
Converts a Mars planetocentric latitude to planetographic latitude. The value for mars_flattening() is used in the conversion.

Parameters:
planetocentric_latitude - the planetocentric latitude in radians.
Returns:
the planetographic latitude in radians.

subsolar_point

public static Point2D subsolar_point(double et)
                              throws SPICE_Exception
Gets the longitude and latitude coordinates of the sub-solar point on Mars at the given time.

Note The longitude returned is east-leading (i.e., positive in the east direction). The latitude is planetographic/geodetic.

Parameters:
et - the input time.
Returns:
a point with the east-leading longitude in the X coordinate and planetographic latititude in the Y coordinate, both in degrees.
Throws:
SPICE_Exception - if the sub-solar point cannot be computed, likely because the planetary constants kernel or the planetary ephemeris kernel is not loaded.

solar_declination

public static double solar_declination(double l_sub_s)
Gets the solar declination for the given solar longitude. The solar declination is the angle between the Sun's rays and the plane of Mars's equator. This value is the result of equation 5 in Allison, 1997:
δs = sin-1(0.4256 sin Ls) + 0.25° sin Ls

where 0.4256 is the sine of Mars's obliquity.

Parameters:
l_sub_s - the planetocentric longitude of the Sun as seen by Mars (in degrees).
Returns:
the solar declination in degrees.
See Also:
"Allison, M. 1997. Accurate analytic representations of solar time and seasons on Mars with applications to the Pathfinder/Surveyor missions. Geophys. Res. Lett. 24, 1967-1970."

solar_altitude

public static double solar_altitude(double target_longitude,
                                    double target_latitude,
                                    double l_sub_s,
                                    double subsolar_longitude)
Gets the solar altitide, or elevation, for a target located at the given coordinates and with the given solar geometry. The solar altitude is the angle between the ground plane and the Sun. (It is not the distance of the Sun above Mars.) The solar altitude is given by the following equation:
a = cos-1(sin δs sin φ + cos δs cos φ cos H

where H is the hour angle Λ - Λs, φ is the target planetographic latitude, and δs is the solar declination, and where Λ is the target west-leading longitude and Λs is the sub-solar west-leading longitude.

Note The longitudes may technically be either west-leading (i.e., west-postitive) or east-leading, as long as they are consistent, because they are only used in a cosine term. The companion function for solar azimuth requires they be west-leading, however, so it's probably easier just to force them to be so.

Finally, the solar zenith angle is simply 90.0 - a.

Parameters:
target_longitude - the west-leading longitude of the target point from which the Sun is observed.
target_latitude - the planetographic latitude of the target point from which the Sun is observed.
l_sub_s - the solar longitude at the time of observation.
subsolar_longitude - the longitude of the sub-solar point at the time of observation.
Returns:
the solar altitude angle in degrees.

solar_altitude

public static double solar_altitude(double target_longitude,
                                    double target_latitude,
                                    double et)
                             throws SPICE_Exception
Gets the solar altitide, or elevation, for a target located at the given coordinates at the given ephemeris time. The solar altitude is the angle between the ground plane and the Sun. (It is not the distance of the Sun above Mars.) et is used to derive the sub-solar longitude Λs and the solar longitude Ls.

Parameters:
target_longitude - the west-leading longitude of the target point from which the Sun is observed.
target_latitude - the planetographic latitude of the target point from which the Sun is observed.
et - the time at which the Sun is observed.
Returns:
the solar azimuth angle in degrees.
Throws:
SPICE_Exception - if the sub-solar longitude or the solar longitude cannot be computed, likely due to missing kernels.
See Also:
solar_altitude(double,double,double,double), subsolar_point(double), Photometry_Utilities.l_sub_s(double)

solar_azimuth

public static double solar_azimuth(double target_longitude,
                                   double target_latitude,
                                   double l_sub_s,
                                   double subsolar_longitude)
Gets the solar azimuth angle for a target located at the given coordinates and with the given solar geometry. The solar azimuth is the (clockwise) compass angle of the Sun's position as viewed from the target site, relative to due north. The solar azimuth is given by the following equation:
A = tan-1(sin H / (cos φ tan δs - sin &phi cos H))

where H is the hour angle Λ - Λs, φ is the target planetographic latitude, and δs is the solar declination, and where Λ is the target west-leading longitude and Λs is the sub-solar west-leading longitude.

Note The longitudes must be west-leading (i.e., west-positive). If they are east-leading (east-positive), this function will return the counter-clockwise angle of the Sun's position.

Parameters:
target_longitude - the west-leading longitude of the target point from which the Sun is observed.
target_latitude - the planetographic latitude of the target point from which the Sun is observed.
l_sub_s - the solar longitude at the time of observation.
subsolar_longitude - the longitude of the sub-solar point at the time of observation.
Returns:
the solar azimuth angle in degrees.

solar_azimuth

public static double solar_azimuth(double target_longitude,
                                   double target_latitude,
                                   double et)
                            throws SPICE_Exception
Gets the solar azimuth angle for a target located at the given coordinates at the given ephemeris time. The solar azimuth is the compass angle of the Sun's position as viewed from the target site, relative to due north. et is used to derive the sub-solar longitude Λs and the solar longitude Ls.

Parameters:
target_longitude - the west-leading longitude of the target point from which the Sun is observed.
target_latitude - the planetographic latitude of the target point from which the Sun is observed.
et - the time at which the Sun is observed.
Returns:
the solar azimuth angle in degrees.
Throws:
SPICE_Exception - if the sub-solar longitude or the solar longitude cannot be computed, likely due to missing kernels.
See Also:
solar_azimuth(double,double,double,double), subsolar_point(double), Photometry_Utilities.l_sub_s(double)

reverse_longitude

public static double reverse_longitude(double longitude)
Reverse a longitude from east-leading to west-leading or vice-versa. The loingitude is assumed to be in degrees, and it will be normalized to the range (0.0, 360.0).

Parameters:
longitude - the longitude to be reversed, in degrees.
Returns:
the reversed longitude, in degrees and normalized to (0.0, 360.0).

normalize_longitude

public static double normalize_longitude(double longitude)
Returns the input longitude normalized to fall in the range (0.0, 360.0).

Parameters:
longitude - the input longitude.
Returns:
the normalized longitude.

find_targeted_observation

public static double[] find_targeted_observation(double lon,
                                                 double lat,
                                                 double alt,
                                                 double guess,
                                                 double beg,
                                                 double end)
                                          throws SPICE_Exception
Gets the observation time and roll angle for a targeted observation with the given initial guess at time, limits, and target coordinates.

This algorithm is lifted directly from the JMARS MRO observation layer; there is, however, no limit imposed on the roll angle.

Parameters:
lon - the target longitude in degrees.
lat - the target planetographic latitude in degrees.
alt - the target altitude above the reference ellipsoid, in km.
guess - an initial guess for the observation time, in seconds.
beg - the lower limit on the observation time.
end - the upper limit on the observation time.
Returns:
a two-element array containing the observation time (et) and the roll angle (in degrees), in that order.
Throws:
SPICE_Exception - if the geometry cannot be determined, typically because of an insufficient SPICE kernel pool.

find_targeted_observation

public static double[] find_targeted_observation(double lon,
                                                 double lat,
                                                 double alt,
                                                 double guess)
                                          throws SPICE_Exception
Gets the observation time and roll angle for a targeted observation with the given initial guess at time and target coordinates. The search is conducted around the initial guess in a range defined by the guess +/- SEARCH_MARGIN seconds.

This algorithm is lifted directly from the JMARS MRO observation layer; there is, however, no limit imposed on the roll angle.

Parameters:
lon - the target longitude in degrees.
lat - the target planetographic latitude in degrees.
alt - the target altitude above the reference ellipsoid, in km.
guess - an initial guess for the observation time, in seconds.
Returns:
a two-element array containing the observation time (et) and the roll angle (in degrees), in that order.
Throws:
SPICE_Exception - if the geometry cannot be determined, typically because of an insufficient SPICE kernel pool.
See Also:
find_targeted_observation(double,double,double,double,double,double)

intersect_planes

public static edu.asu.jmars.util.HVector[] intersect_planes(edu.asu.jmars.util.HVector n1,
                                                            edu.asu.jmars.util.HVector p1,
                                                            edu.asu.jmars.util.HVector n2,
                                                            edu.asu.jmars.util.HVector p2)
Derives the line that is the intersection of two planes. The line is defined by a point and a direction vector.

This algorithm is lifted directly from the JMARS MRO observation layer.

Parameters:
n1 - the unit normal vector for plane 1.
p1 - a point on plane 1.
n2 - the unit normal vector for plane 2.
p2 - a point on plane 2.
Returns:
a two-element array of vectors, the first of which is the intersecting line's point and the second of which is the direction vector, or null if the planes are parallel.

recgeo_ographic

public static double[] recgeo_ographic(double[] rec)
                                throws SPICE_Exception
Converts a rectangular coordinate 3-vector to geographic coordinates in the east-leading planetographic system. The returned 3-vector consists of longitude, latitude, and altitude, in that order. Longitude and latitude are in radians. Altitude is measured above the reference ellipsoid, defined by the mars_radii(), in the same units as the input coordinates.

Parameters:
rec - the rectangular coordinates.
Returns:
the geographic coordinates, east-leading planetographic, with longitude and latitude in radians and with altitude in the same units as the input coordinates.
Throws:
SPICE_Exception - if the SPICE kernel pool does not contain sufficient data to perform the conversion.

recgeo_ocentric

public static double[] recgeo_ocentric(double[] rec)
                                throws SPICE_Exception
Converts a rectangular coordinate 3-vector to geographic coordinates in the east-leading planetocentric system. The returned 3-vector consists of longitude, latitude, and altitude, in that order. Longitude and latitude are in radians. Altitude is measured above the reference ellipsoid, defined by the mars_radii(), in the same units as the input coordinates.

Parameters:
rec - the rectangular coordinates.
Returns:
the geographic coordinates, east-leading planetocentric, with longitude and latitude in radians and with altitude in the same units as the input coordinates.
Throws:
SPICE_Exception - if the SPICE kernel pool does not contain sufficient data to perform the conversion.

point2d_degrees

public static Point2D point2d_degrees(Point2D point2d_radians)
Converts a geographic point whose coordinates are in radians to one whose coordinates are in degrees. The longitude coordinate (Point2D.getX()) is normalized to fall within the range 0.0, 360.0 degrees.

Parameters:
point2d_radians - a geographic point whose coordinates are in radians.
Returns:
a geographic point whose coordinates are in degrees, with the longitude normalized to 0.0, 360.0 degrees.

point2d_radians

public static Point2D point2d_radians(Point2D point2d_degrees)
Converts a geographic point whose coordinates are in degrees to one whose coordinates are in radians. The longitude coordinate (Point2D.getX()) is normalized to fall within the range 0.0, 2π radians.

Parameters:
point2d_degrees - a geographic point whose coordinates are in degrees.
Returns:
a geographic point whose coordinates are in radians, with the longitude normalized to 0.0, 2π radians.

HiRISE

Copyright (C) Arizona Board of Regents on behalf of the Planetary Image Research Laboratory, Lunar and Planetary Laboratory at the University of Arizona