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