CARTOGRAPHY(3)
NAME
img2sphere, optimum_scale, plane2sphere, pow2_scale,
sphere2img, sphere2plane - functions for mapping and scaling
between plate, heliographic, and various map coordinate sys-
tems.
Syntax
#include <soi_util.h>
int img2sphere (x, y, ang_r, latc, lonc, pa, rho, lat, lon, sinlat,
coslat, sigma, mu, chi)
double x, y, ang_r, latc, lonc, pa;
double *rho, *lat, *lon, *sinlat, *coslat, *sigma, *mu, *chi;
double optimum_scale (xscale, yscale, cone_lat, cone_radius)
double xscale, yscale, double cone_lat, double cone_radius;
int plane2sphere (x, y, latc, lonc, lat, lon, projection)
double x, y, latc, lonc;
double *lat, *lon;
int projection;
int pow2_scale (scale, cone_radius, cone_lat, cone_lon, projection)
double scale, cone_radius, cone_lat, cone_lon;
int projection;
int sphere2img (lat, lon, latc, lonc, x, y, xcenter, ycenter, rsun,
pos_angle, eccentricity, ellipse_pa, x_inverted, y_inverted)
double lat, lon, latc, lonc;
double *x, *y;
double xcenter, ycenter, rsun, pos_angle, eccentrcity, ellipse_pa;
int x_inverted, y_inverted;
int sphere2plane (lat, lon, latc, lonc, x, y, projection)
double lat, lon, latc, lonc;
double *x, *y;
int projection;
DESCRIPTION
img2sphere provides a mapping from coordinates on a solar
image to both heliocentric and heliographic coordinates.
The image coordinates x and y must be specified relative to
the center of the solar disc, and in units of the true semi-
diameter of the Sun, i.e. in solar radii. The angular
radius of the sun ang_r, which is the apparent semi-
diameter, along with the latitude and longitude of disc
center and the position angle of solar north on the image,
must all be specified in radians. It is assumed that the
image is direct, with x increasing westward (on the sky) and
y increasing northward, and that the position angle pa
increases westward from north. The return values are the
heliographic coordinates lat and lon, the heliocentric
angles point:sun_center:observer (rho) and
point:observer:sun_center (sigma), the cosine of the angle
between the point:observer line and the local normal (mu),
and the position angle relative to solar north (chi). All
angles are in radians. The sine and cosine of the latitude
are also provided as byproducts.
The function optimum_scale returns the scale, in degrees per
pixel, that will retain the original image resolution at the
"best" location in the mapped image. For the purpose of
determining the "original image resolution", it is assumed
that the selection cone is on the observer's central meri-
dian and that the observer's heliographic latitude is as
close as possible to the cone but not exceeding +/- 7.5
degrees.
plane2sphere() performs the inverse mapping from rectangular
coordinates x, y on a map in a particular projection to
heliographic (or geographic) coordinates latitude (lat) and
longitude (lon), in radians. The map coordinates are first
transformed into arc and azimuth coordinates relative to the
center of the map according to the appropriate inverse
transformation for the projection, and thence to latitude
and longitude from the known heliographic coordinates of the
map center (latc and lonc) (in radians). The scale of the
map coordinates is assumed to be in units of radians at the
map center (or other appropriate location of minimum distor-
tion).
sphere2plane() performs a direct mapping from heliographic
(or geographic) coordinates latitude (lat) and longitude
(lon), in radians, to rectangular coordinates x, y on a map
in the given projection. The map coordinates are returned
in units of radians from the specified map center location
(or other appropriate location of minimum distortion) at the
central scale.
The following projections are supported:
RECTANGULAR 0 "Rectangular": [x,y] <-> [lon,lat]
GNOMONIC 1 Gnomonic, or central
POSTEL 2 Postel's azimuthal equidistant
STEREOGRAPHIC 3 Stereographic
ORTHOGRAPHIC 4 Orthographic
LAMBERT 5 Lambert's azimuthal
CYLEQA 6 cylindrical equal-area
SINEQA 7 sinusoidal equal-area
MERCATOR 8 Mercator's
AERIAL 9 Aerial (perspective from a finite distance)
pow2_scale() determines a map size for a square map with
2**n pixels on a side that will contain the selected cone at
the given scale. The scale is assumed given at the center
in units of heliographic (or geographic) degrees per pixel.
The same projections are supported as for plane2sphere().
sphere2img() performs a mapping from heliographic coordi-
nates latitude (lat) and longitude (lon) (in radians) to
plate location (x and y) on an image of the sun. The plate
location is in units of the image radius and is given rela-
tive to the image center.
The required auxiliary arguments are the heliographic coor-
dinates of disc center (latc and lonc) (in radians), the
plate location of the image center in units of the image
radius (xcenter and ycenter), the apparent semi-diameter of
the solar disc rsun, in plate coordinates (pixels), the
position angle (pos_angle) of solar north on the plate
(measured eastward from north) in radians, the eccentricity
of the ellipse fitting the solar image disc, the position
angle of the major axis of the ellipse (also measured east-
ward from north) in radians (ellipse_pa), and two flags,
x_inverted and y_inverted, for which non-zero values signify
that the original image is inverted in the x- and y- direc-
tions respectively. Note that the reference point for the
plate coordinate system in which the disc center is speci-
fied is arbitrary.
DIAGNOSTICS
img2sphere() returns 1 if the mapped point is off the solar
disk (in which case the returned heliographic coordinates
and mu are meaningless), 0 otherwise.
sphere2img() returns 0 if the requested point is on the hem-
isphere visible to the observer, 1 otherwise; the plate
coordinates are correct for a transparent Sun.
plane2sphere() returns -1 if the requested point on the map
does not project back to the sphere, 1 if it projects to a
point on the hidden hemisphere (if that makes sense), 0 oth-
erwise. It also returns 1 if the requested point is not the
principal value on certain periodic mappings, (rectangular,
Mercator, and cylindrical and sinusoidal equal-area).
BUGS
pow2_scale() ignores the coordinates of the selected cone,
assuming it can be located at disc center.
In sphere2img(), the finite distance to the Sun is accounted
for in the mapping, but it is assumed that the distance is
exactly 1.0 AU. There is no correction for the general
relativistic geometric distortion. The visible hemisphere
status returned is based on the heliographic distance from
disc center; it is incorrect for points between about 89.7
degrees and 90 degrees from disc center, which are actually
over the limb; this region is about 0.01 arc-sec thick. The
correction for an elliptical image has not been tested very
thoroughly. Likewise the correct functioning of the mapping
in images in which the plate scale is different in different
directions has not been verified.
SEE ALSO
AUTHORS
Rick Bogart, Luiz Sa
HISTORY
1999-04-23 SOI Version 4.2