void latsrf_c ( ConstSpiceChar * method,
ConstSpiceChar * target,
SpiceDouble et,
ConstSpiceChar * fixref,
SpiceInt npts,
ConstSpiceDouble lonlat[][2],
SpiceDouble srfpts[][3] )
Map array of planetocentric longitude/latitude coordinate pairs
to surface points on a specified target body.
The surface of the target body may be represented by a triaxial
ellipsoid or by topographic data provided by DSK files.
DSK
FRAMES
PCK
TIME
COORDINATES
DSK
GEOMETRY
SURFACE
Variable I/O Description
-------- --- --------------------------------------------------
method I Computation method.
target I Name of target body.
et I Epoch in TDB seconds past J2000 TDB.
fixref I Body-fixed, body-centered target body frame.
npts I Number of coordinate pairs in input array.
lonlat I Array of longitude/latitude coordinate pairs.
srfpts O Array of surface points.
method is a short string providing parameters defining
the computation method to be used. In the syntax
descriptions below, items delimited by brackets
are optional.
`method' may be assigned the following values:
"ELLIPSOID"
The surface point computation uses a triaxial
ellipsoid to model the surface of the target
body. The ellipsoid's radii must be available
in the kernel pool.
"DSK/UNPRIORITIZED[/SURFACES = <surface list>]"
The surface point computation uses topographic
data to model the surface of the target body.
These data must be provided by loaded DSK
files.
The surface list specification is optional. The
syntax of the list is
<surface 1> [, <surface 2>...]
If present, it indicates that data only for the
listed surfaces are to be used; however, data
need not be available for all surfaces in the
list. If absent, loaded DSK data for any surface
associated with the target body are used.
The surface list may contain surface names or
surface ID codes. Names containing blanks must
be delimited by double quotes, for example
SURFACES = "Mars MEGDR 128 PIXEL/DEG"
If multiple surfaces are specified, their names
or IDs must be separated by commas.
See the Particulars section below for details
concerning use of DSK data.
Neither case nor white space are significant in
`method', except within double-quoted strings. For
example, the string " eLLipsoid " is valid.
Within double-quoted strings, blank characters are
significant, but multiple consecutive blanks are
considered equivalent to a single blank. Case is
not significant. So
"Mars MEGDR 128 PIXEL/DEG"
is equivalent to
" mars megdr 128 pixel/deg "
but not to
"MARS MEGDR128PIXEL/DEG"
target is the name of the target body. `target' is
case-insensitive, and leading and trailing blanks in
`target' are not significant. Optionally, you may
supply a string containing the integer ID code for
the object. For example both "MOON" and "301" are
legitimate strings that indicate the Moon is the
target body.
When the target body's surface is represented by a
tri-axial ellipsoid, this routine assumes that a
kernel variable representing the ellipsoid's radii is
present in the kernel pool. Normally the kernel
variable would be defined by loading a PCK file.
et is the epoch for which target surface data will be
selected, if the surface is modeled using DSK data.
In this case, only segments having time coverage that
includes the epoch `et' will be used.
`et' is ignored if the target is modeled as an
ellipsoid.
`et' is expressed as TDB seconds past J2000 TDB.
fixref is the name of a body-fixed reference frame centered
on the target body. `fixref' may be any such frame
supported by the SPICE system, including built-in
frames (documented in the Frames Required Reading)
and frames defined by a loaded frame kernel (FK). The
string `fixref' is case-insensitive, and leading and
trailing blanks in `fixref' are not significant.
The output surface points in the array `srfpts' will be
expressed relative to this reference frame.
npts is the number of coordinate pairs in the array `lonlat'.
lonlat is an array of pairs of planetocentric longitudes and
latitudes of surface points. Elements
lonlat[0][i]
lonlat[1][i]
are, respectively, the planetocentric longitude and
latitude of the Ith surface point, where `i' ranges
from 0 to npts-1.
The units of longitude and latitude are radians.
srfpts is an array of target body surface points
corresponding to the pairs of coordinates in the
input `lonlat' array. Elements
srfpts[0][i]
srfpts[1][i]
srfpts[2][i]
are the Cartesian coordinates, expressed in the
reference frame designated by `fixref', of the surface
point corresponding to the Ith pair of input
coordinates, where `i' ranges from 0 to npts-1.
If there are multiple solutions for a given input
coordinate pair, this routine will return the point
at those coordinates having the greatest distance
from the origin of the coordinate system.
None.
1) If the target body name
input string cannot be converted to an integer ID code, the
error SPICE(IDCODENOTFOUND) is signaled.
2) If the input target body-fixed frame `fixref' is not
recognized, the error SPICE(NOFRAME) is signaled. A frame
name may fail to be recognized because a required frame
specification kernel has not been loaded; another cause is a
misspelling of the frame name.
3) If the input frame `fixref' is not centered at the target body,
the error SPICE(INVALIDFRAME) is signaled.
4) If data are not available to convert between the frame
`fixref' and the frame of a DSK segment of interest, the error
will be signaled by a routine in the call tree of this
routine.
5) If the input argument `method' cannot be parsed, the error
will be signaled either by this routine or by a routine in
the call tree of this routine.
6) If the computation method specifies an ellipsoidal target
model, and if triaxial radii of the target body have not been
loaded into the kernel pool prior to calling latsrf_c, the
error will be diagnosed and signaled by a routine in the call
tree of this routine.
7) The target must be an extended body: if the computation
method specifies an ellipsoidal target model, and if any of
the radii of the target body are non-positive, the error will
be signaled by routines in the call tree of this routine.
8) If `method' specifies that the target surface is represented by
DSK data, and no DSK files are loaded for the specified
target, the error is signaled by a routine in the call tree
of this routine.
9) If `method' specifies that the target surface is represented
by DSK data, and data representing the portion of the surface
corresponding to the coordinates provided in `lonlat' are not
available, an error will be signaled by a routine in the call
tree of this routine.
10) If a surface point cannot be computed because the ray
corresponding to a longitude/latitude pair fails to intersect
the target surface as defined by the plate model, the error
SPICE(NOINTERCEPT) is signaled.
11) If the surface point corresponding to a longitude/latitude
pair in `lonlat' does not have matching longitude and latitude
(because it is on the opposite side of the origin), the error
SPICE(SHAPENOTSUPPORTED) is signaled.
12) If any input string argument pointer is null, the error
SPICE(NULLPOINTER) will be signaled.
13) If any input string argument is empty, the error
SPICE(EMPTYSTRING) will be signaled.
Appropriate kernels must be loaded by the calling program before
this routine is called.
The following data are required:
- Shape data for the target body:
PCK data:
If the target shape is modeled as an ellipsoid,
triaxial radii for the target body must be loaded into
the kernel pool. Typically this is done by loading a
text PCK file via furnsh_c.
DSK data:
If the target shape is modeled by DSK data, DSK files
containing topographic data for the target body must be
loaded. If a surface list is specified, data for at
least one of the listed surfaces must be loaded.
- Target body orientation data: these may be provided in a
text or binary PCK file. In some cases, target body
orientation may be provided by one more more CK files. In
either case, data are made available by loading the files
via furnsh_c.
The following data may be required:
- Frame data: if a frame definition is required to convert
between the body-fixed frame of the target and the frame of
a DSK segment providing topographic data, that definition
must be available in the kernel pool. Typically the
definition is supplied by loading a frame kernel via furnsh_c.
- Surface name-ID associations: if surface names are specified
in `method', the association of these names with their
corresponding surface ID codes must be established by
assignments of the kernel variables
NAIF_SURFACE_NAME
NAIF_SURFACE_CODE
NAIF_SURFACE_BODY
Normally these associations are made by loading a text
kernel containing the necessary assignments. An example of
such a set of assignments is
NAIF_SURFACE_NAME += 'Mars MEGDR 128 PIXEL/DEG'
NAIF_SURFACE_CODE += 1
NAIF_SURFACE_BODY += 499
- SCLK data: if the target body's orientation is provided by
CK files, an associated SCLK kernel must be loaded.
In all cases, kernel data are normally loaded once per program
run, NOT every time this routine is called.
This routine is intended to be used for target body surfaces that
have a unique radius for each pair of planetocentric longitude
and latitude coordinates.
If the target surface is represented by topographic data, it is
possible for there to be multiple surface points at a given
planetocentric longitude and latitude. For example, this can
occur if the surface has features such as cliffs, caves, or
arches.
For more complex surfaces, the routine
DSKSXV {DSK, ray-surface intercept, vectorized}
may be more suitable. That routine works with rays having vertices
anywhere outside of the target body.
Planetocentric coordinates
==========================
Planetocentric longitude and latitude are defined as follows:
Longitude of a point P is the angle between the prime meridian
and the meridian containing P. The direction of increasing
longitude is from the +X axis towards the +Y axis.
Latitude of a point P is the angle from the XY plane of the
ray from the origin through the point.
Using DSK data
==============
DSK loading and unloading
-------------------------
DSK files providing data used by this routine are loaded by
calling furnsh_c and can be unloaded by calling unload_c or
kclear_c. See the documentation of furnsh_c for limits on numbers
of loaded DSK files.
For run-time efficiency, it's desirable to avoid frequent
loading and unloading of DSK files. When there is a reason to
use multiple versions of data for a given target body---for
example, if topographic data at varying resolutions are to be
used---the surface list can be used to select DSK data to be
used for a given computation. It is not necessary to unload
the data that are not to be used. This recommendation presumes
that DSKs containing different versions of surface data for a
given body have different surface ID codes.
DSK data priority
-----------------
A DSK coverage overlap occurs when two segments in loaded DSK
files cover part or all of the same domain---for example, a
given longitude-latitude rectangle---and when the time
intervals of the segments overlap as well.
When DSK data selection is prioritized, in case of a coverage
overlap, if the two competing segments are in different DSK
files, the segment in the DSK file loaded last takes
precedence. If the two segments are in the same file, the
segment located closer to the end of the file takes
precedence.
When DSK data selection is unprioritized, data from competing
segments are combined. For example, if two competing segments
both represent a surface as sets of triangular plates, the
union of those sets of plates is considered to represent the
surface.
Currently only unprioritized data selection is supported.
Because prioritized data selection may be the default behavior
in a later version of the routine, the UNPRIORITIZED keyword is
required in the `method' argument.
Syntax of the METHOD input argument
-----------------------------------
The keywords and surface list in the `method' argument
are called "clauses." The clauses may appear in any
order, for example
DSK/<surface list>/UNPRIORITIZED
DSK/UNPRIORITIZED/<surface list>
UNPRIORITIZED/<surface list>/DSK
The simplest form of the `method' argument specifying use of
DSK data is one that lacks a surface list, for example:
"DSK/UNPRIORITIZED"
For applications in which all loaded DSK data for the target
body are for a single surface, and there are no competing
segments, the above string suffices. This is expected to be
the usual case.
When, for the specified target body, there are loaded DSK
files providing data for multiple surfaces for that body, the
surfaces to be used by this routine for a given call must be
specified in a surface list, unless data from all of the
surfaces are to be used together.
The surface list consists of the string
SURFACES =
followed by a comma-separated list of one or more surface
identifiers. The identifiers may be names or integer codes in
string format. For example, suppose we have the surface
names and corresponding ID codes shown below:
Surface Name ID code
------------ -------
"Mars MEGDR 128 PIXEL/DEG" 1
"Mars MEGDR 64 PIXEL/DEG" 2
"Mars_MRO_HIRISE" 3
If data for all of the above surfaces are loaded, then
data for surface 1 can be specified by either
"SURFACES = 1"
or
"SURFACES = \"Mars MEGDR 128 PIXEL/DEG\""
Double quotes are used to delimit the surface name because
it contains blank characters.
To use data for surfaces 2 and 3 together, any
of the following surface lists could be used:
"SURFACES = 2, 3"
"SURFACES = \"Mars MEGDR 64 PIXEL/DEG\", 3"
"SURFACES = 2, Mars_MRO_HIRISE"
"SURFACES = \"Mars MEGDR 64 PIXEL/DEG\", Mars_MRO_HIRISE"
An example of a `method' argument that could be constructed
using one of the surface lists above is
"DSK/UNPRIORITIZED/SURFACES = \"Mars MEGDR 64 PIXEL/DEG\", 3"
The numerical results shown for this example may differ across
platforms. The results depend on the SPICE kernels used as input,
the compiler and supporting libraries, and the machine specific
arithmetic implementation.
1) In the following example program, the file
phobos512.bds
is a DSK file containing a type 2 segment that provides a
plate model representation of the surface of Phobos.
Find the surface points on a target body corresponding to a
given planetocentric longitude/latitude grid. In order to
duplicate the example output, the kernel name
phobos512.bds
should be supplied at the prompt.
Example code begins here.
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
/.
Local constants
./
#define FILSIZ 256
#define MAXN 100
/.
Local variables
./
SpiceChar dsk [ FILSIZ ];
SpiceChar * fixref;
SpiceChar * method;
SpiceChar * target;
SpiceDouble dlat;
SpiceDouble dlon;
SpiceDouble et;
SpiceDouble grid [MAXN][2];
SpiceDouble lat;
SpiceDouble lat0;
SpiceDouble lon;
SpiceDouble lon0;
SpiceDouble srfpts [MAXN][3];
SpiceDouble xlat;
SpiceDouble xlon;
SpiceDouble xr;
SpiceInt i;
SpiceInt j;
SpiceInt n;
SpiceInt nlat;
SpiceInt nlon;
/.
Set target, reference frame, and epoch.
./
target = "phobos";
fixref = "iau_phobos";
et = 0.0;
/.
Use DSK data to represent the surface.
./
method = "DSK/UNPRIORITIZED";
/.
Set the grid dimensions.
./
nlon = 6;
nlat = 3;
/.
Derive evenly spaced grid separations and starting
values in the longitude and latitude dimensions.
Units are degrees.
./
lat0 = 90.0;
lon0 = 0.0;
dlat = 180.0 / (nlat + 1);
dlon = 360.0 / nlon;
/.
Prompt for the name of the DSK to read.
./
prompt_c ( "Enter DSK name > ", FILSIZ, dsk );
/.
Load the DSK file.
./
furnsh_c ( dsk );
/.
Now generate the grid points. We generate
points along latitude bands, working from
north to south. The latitude range is selected
to range from +45 to -45 degrees. Longitude
ranges from 0 to 300 degrees. The increment
is 45 degrees for latitude and 60 degrees for
longitude.
./
n = 0;
for ( i = 0; i < nlat; i++ )
{
lat = rpd_c() * ( lat0 - (i+1)*dlat );
for ( j = 0; j < nlon; j++ )
{
lon = rpd_c() * ( lon0 + j*dlon );
grid[n][0] = lon;
grid[n][1] = lat;
++n;
}
}
/.
Find the surface points corresponding to the grid points.
./
latsrf_c ( method, target, et,
fixref, n, grid, srfpts );
/.
Print out the surface points in latitudinal
coordinates and compare the derived lon/lat values
to those of the input grid.
./
for ( i = 0; i < n; i++ )
{
/.
Use recrad_c rather than reclat_c to produce
non-negative longitudes.
./
recrad_c ( srfpts[i], &xr, &xlon, &xlat );
printf ( "\n"
"Intercept for grid point %d:\n"
" Cartesian coordinates: "
"(%11.4e, %11.4e, %11.4e)\n"
" Latitudinal Coordinates:\n"
" Longitude (deg): %12.6f\n"
" Latitude (deg): %12.6f\n"
" Radius (km): %12.6f\n"
"\n"
" Original Grid Coordinates:\n"
" Longitude (deg): %12.6f\n"
" Latitude (deg): %12.6f\n"
"\n",
(int)i,
srfpts[i][0], srfpts[i][1], srfpts[i][2],
xlon*dpr_c(), xlat*dpr_c(), xr,
grid[i][0]*dpr_c(), grid[i][1]*dpr_c() );
}
return ( 0 );
}
When this program was executed on a PC/Linux/gcc 64-bit
platform, the output for the first 3 points and the last 3 points
(the rest of the output is not shown due to its large volume)
was:
Enter DSK name > phobos512.bds
Intercept for grid point 0:
Cartesian coordinates: ( 7.1817e+00, 0.0000e+00, 7.1817e+00)
Latitudinal Coordinates:
Longitude (deg): 0.000000
Latitude (deg): 45.000000
Radius (km): 10.156402
Original Grid Coordinates:
Longitude (deg): 0.000000
Latitude (deg): 45.000000
Intercept for grid point 1:
Cartesian coordinates: ( 3.5820e+00, 6.2042e+00, 7.1640e+00)
Latitudinal Coordinates:
Longitude (deg): 60.000000
Latitude (deg): 45.000000
Radius (km): 10.131412
Original Grid Coordinates:
Longitude (deg): 60.000000
Latitude (deg): 45.000000
Intercept for grid point 2:
Cartesian coordinates: (-3.6854e+00, 6.3832e+00, 7.3707e+00)
Latitudinal Coordinates:
Longitude (deg): 120.000000
Latitude (deg): 45.000000
Radius (km): 10.423766
Original Grid Coordinates:
Longitude (deg): 120.000000
Latitude (deg): 45.000000
...
Intercept for grid point 15:
Cartesian coordinates: (-8.2374e+00, 1.5723e-15, -8.2374e+00)
Latitudinal Coordinates:
Longitude (deg): 180.000000
Latitude (deg): -45.000000
Radius (km): 11.649512
Original Grid Coordinates:
Longitude (deg): 180.000000
Latitude (deg): -45.000000
Intercept for grid point 16:
Cartesian coordinates: (-3.6277e+00, -6.2833e+00, -7.2553e+00)
Latitudinal Coordinates:
Longitude (deg): 240.000000
Latitude (deg): -45.000000
Radius (km): 10.260572
Original Grid Coordinates:
Longitude (deg): 240.000000
Latitude (deg): -45.000000
Intercept for grid point 17:
Cartesian coordinates: ( 3.2881e+00, -5.6952e+00, -6.5762e+00)
Latitudinal Coordinates:
Longitude (deg): 300.000000
Latitude (deg): -45.000000
Radius (km): 9.300154
Original Grid Coordinates:
Longitude (deg): 300.000000
Latitude (deg): -45.000000
1) This routine assumes that the origin of the body-fixed
reference frame associated with the target body is located in
the interior of that body.
2) The results returned by this routine may not be meaningful
if the target surface has multiple surface points associated
with some (longitude, latitude) coordinates.
None.
N.J. Bachman (JPL)
-CSPICE Version 1.0.0, 10-FEB-2016 (NJB)
map latitudinal coordinates to Cartesian surface points
map latitudinal coordinates to DSK surface points
Link to routine latsrf_c source file latsrf_c.c
|