New

git-svn-id: http://svn.osgeo.org/metacrs/proj/trunk@776 4e78687f-474d-0410-85f9-8d5e500ac6b2

4 files changed, 757 insertions, 0 deletions

diff --git a/man/man1/geod.1 b/man/man1/geod.1
new file mode 100644
index 00000000..36f32717
--- /dev/null
+++ b/man/man1/geod.1
@@ -0,0 +1,202 @@
+.\" @(#)geod.1 - 1.1
+.nr LL 5.5i
+.ad b
+.hy 1
+.TH GEOD 1 "94/10/29 Rel. 4, Ver. BETA" "GIE"
+.SH NAME
+geod \- direct geodesic computations
+.br
+invgeod \- inverse geodesic computations
+.SH SYNOPSIS
+.B geod
+[
+.B \-afFIlptwW
+[
+.I args
+] ] [
+.B +args
+]
+file[s]
+.br
+.B invgeod
+[
+.B \-afFIlptwW
+[
+.I args
+] ] [
+.B +args
+]
+file[s]
+.SH DESCRIPTION
+.I Geod
+(direct) and
+.I invgeod
+(inverse)
+perform geodesic (\(``Great Circle\('') computations for determining
+latitude, longitude and back azimuth of a terminus point
+given a initial point latitude, longitude, azimuth and distance (direct) or
+the forward and back azimuths and distance between an initial and
+terminus point latitudes and longitudes (inverse).
+.PP
+The following runline control parameters can appear in any order:
+.TP
+.B \-I
+Specifies that the inverse geodesic computation is to be performed.
+May be used with execution of
+.B goed
+as an alternative to
+.B invgeod
+execution.
+.TP
+.B \-a
+Latitude and longitudes of the initial and terminal points,
+forward and back azimuths and distance are output.
+.TP
+.BI \-t "a"
+.I A
+specifies a character employed as the first character to denote
+a control line to be passed through without processing.
+.TP
+.BI \-le
+Gives a listing of all the ellipsoids that may be selected with the
+.B +ellps=
+option.
+.TP
+.BI \-lu
+Gives a listing of all the units that may be selected with the
+.B +units=
+option.
+.TP
+.BI \-[f|F] " format"
+.I Format
+is a
+.I printf
+format string to control the output form of the geographic coordinate values
+(\fBf\fR) or distance value (\fBF\fR).
+The default mode is DMS for geographic coordinates and "%.3f" for distance.
+.TP
+.BI \-[w|W] n
+.I N
+is the number of significant fractional digits to employ for
+seconds output (when the option is not specified,
+.B \-w3
+is assumed).
+When
+.B \-W
+is employed the fields will be constant width with leading zeroes.
+.TP
+.B \-p
+This option causes the azimuthal values to be output as unsigned
+numbers between 0 and 360\(de.
+.PP
+The
+.B +args
+run-line arguments are associated with geodetic parameters
+for specifying the ellipsoidal or sphere to use.
+See
+.B proj
+documentation for full list of these parameters and contrl.
+The options are processed in left to right order
+from the run line.
+Reentry of an option is ignored with the first occurance assumed to
+be the desired value.
+.PP
+One or more
+.I files
+(processed in left to right order)
+specify the source of data to be transformed.
+A \- will specify the location of processing standard input.
+If no files are specified, the input is assumed to be from
+.I stdin.
+.PP
+For direct determinations input data must be in latitude,
+longitude, azimuth and distance order and output will be
+latitude, longitude and back azimuth of the terminus point.
+Latitude, longitude of the initial and terminus point are
+input for the inverse mode and respective forward and back
+azimuth from the initial and terminus points are output along
+with the distance between the points.
+.PP
+Input geographic coordinates
+(latitude and longitude) and azimuthal data must be in DMS format and input
+distance data must be in units consistent with the ellipsoid
+major axis or sphere radius units.
+Output geographic coordinates will be in DMS
+(if the
+.B \-f
+switch is not employed) to 0.001"
+with trailing, zero-valued minute-second fields deleted.
+Output distance data will be in the same units as the ellipsoid or
+sphere radius.
+.PP
+The Earth's ellipsoidal figure may be selected in the same
+manner as program
+.B proj
+by using
+.B "+ellps=, +a=, +es=,"
+etc.
+.PP
+.I Geod
+may also be used to determine intermediate points along either
+a geodesic line between two points or along an arc of specified distance
+from a geographic point.
+In both cases an initial point must be specified with
+.BI +lat_1= lat
+and
+.BI +lon_1= lon
+parameters and either a terminus point
+.BI +lat_2= lat
+and
+.BI +lon_2= lon
+or a distance and azimuth from the initial point with
+.BI +S= distance
+and
+.BI +A= azimuth
+must be specified.
+.PP
+If points along a geodesic are to be determined then either
+.BI +n_S= integer
+specifying the number of intermediate points and/or
+.BI +del_S= distance
+specifying the incremental distance between points must be specified.
+.PP
+To determine points along an arc equidistant from the initial point both
+.BI +del_A= angle
+and
+.BI +n_A= integer
+must be specified which determine the respective angular increments
+and number of points to be determined.
+.RE
+.SH EXAMPLE
+The following script determines the geodesic azimuths and distance in
+U.S. stature miles from Boston, MA, to Portland, OR:
+.RS 5
+ \f(CWgeod +ellps=clrk66 <<EOF -I +units=us-mi
+ 42d15'N 71d07'W 45d31'N 123d41'W
+ EOF\fR
+.RE
+which gives the results:
+.RS 5
+ \f(CW-66d31'50.141"   75d39'13.083"   2587.504
+.RE
+where the first two values are the
+azimuth from Boston to Portland, the back azimuth from Portland to
+Boston followed by the distance.
+.PP
+An example of forward geodesic use is to use the Boston location and determine
+Portland's location by azimuth and distance:
+.RS 5
+ \f(CWgeod +ellps=clrk66 <<EOF +units=us-mi
+ 42d15'N 71d07'W -66d31'50.141" 2587.504
+ EOF\fR
+.RE
+which gives:
+.RS 5
+ \f(CW45d31'0.003"N   123d40'59.985"W 75d39'13.094"\fR
+.RE
+Note: lack of precision in the distance value compromises
+the precision of the Portland location.
+.SH SEE ALSO
+Thomas, P.D., 1970,
+.I "Spheroidal Geodesics, Reference Systems & Local Geometry:"
+U.S. Naval Oceanographic  Office, S-138.
diff --git a/man/man1/nad2nad.1 b/man/man1/nad2nad.1
new file mode 100644
index 00000000..ebc4562a
--- /dev/null
+++ b/man/man1/nad2nad.1
@@ -0,0 +1,187 @@
+.\" release 4
+.nr LL 5.5i
+.ad b
+.hy 1
+.TH PROJ 1 "93/08/25 Rel. 1, Ver. REL" "GIE"
+.SH NAME
+nad2nad \- North American Datum conversion filter
+.SH SYNOPSIS
+.B nad2nad
+[
+.B \-eEfihortwW
+[
+.I args
+] ] [
+.B +args
+]
+file[s]
+.SH DESCRIPTION
+Program
+.B nad2nad
+is a filter to convert data between North
+America Datum 1927 (NAD27) and North American Datum 1983.
+.B nad2nad
+can optionally process both State Plane Coordinate System (SPCS) and
+Universal Transverse Mercator (UTM) grid data as well
+as geographic data for both input and output.
+.PP
+The following control parameters can appear in any order:
+.TP
+.BI \-[i|o] " keyword[,keyword]"
+The
+.B \-i
+and
+.B \-o
+option expect keyword arguments which define various characteristics and
+processing modes of the
+respective input data.
+Usage allows multiple arguments to be included with a \- operator
+when separated by commas.
+Datum conversion requires the data to be in geographic coordinates, but
+.B nad2nad
+will allow conversion of data to and from SPCS or UTM grid systems.
+The following are keywords and arguments reconized by both the
+.B \-i
+and
+.B \-o
+that will apply to respective input and output conversion of user
+data to internal geographic coordinates:
+.RS 1in
+.TP
+.B 27|83
+datum of data
+.TP
+.BI utm= n
+.B UTM
+coordinates in meters for zone
+.I n
+.TP
+.BI spcs= n
+for data in
+.B SPCS
+coordinates, where
+.I n
+is state zone number.
+.TP
+.B feet
+data units are in U.S. Surveyor's feet.
+This is allowed only when the
+.I spcs
+option been previously used.
+Default coordinates are in meters.
+.TP
+.B bin
+for data in binary form.
+.TP
+.B rev
+data in lat-lon order rather than default lon-lat order.
+.TP
+.BI hp= ss
+use high precision conversion zone
+.I ss.
+Certain States have ancillary correction tables to further refine
+the basic conus table.
+.I Ss
+key and States are:
+.RS .5in
+FL Florida
+.br
+MD Maryland
+.br
+TN Tennessee
+.br
+WI Wisconsin
+.br
+WO Washington, Oregon and northern part of California.
+.RE
+.RE
+.TP
+.BI \-t "a"
+.I A
+specifies a character employed as the first character to denote
+a control line to be passed through without processing.
+This option applicable to ascii input only.
+(# is the default value).
+.TP
+.BI \-e " string"
+.I String
+is an arbitrary string to be output if an error is detected during
+data transformations.
+The default value is: *\et*.
+Note that if the
+.B "\-o bin"
+option is employed, an error is output as HUGE_VAL for both values.
+.TP
+.BI \-r " region"
+specifies which regional conversion table to employ which are identified
+by the following:
+.RS .5in
+conus \- conterminous 48 States
+.br
+alaska \- State of Alaska
+.br
+hawaii \- State of Hawaii
+.br
+prvi \- Puerto Rico and Virgin Islands
+.br
+stgeorge \- St. George Is, Alaska
+.br
+stpaul \- St. Paul Is, Alaska
+.br
+stlrnc \- St. Lawrence Is, Alaska
+.TP
+.B \-E
+Input coordinates are echoed to output before ouput values.
+.RE
+.TP
+.BI \-f " format"
+.I Format
+is a
+.I printf
+format string to control the form of the output values.
+For inverse projections, the output will be in degrees when this option
+is employed.
+If a format is specified for inverse projection the
+output data will be in decimal degrees.
+The default format is \(``%.2f\('' for forward projection and DMS
+for inverse.
+.TP
+.BI \-[w|W] n
+.I N
+is the number of significant fractional digits to employ for
+seconds output (when the option is not specified,
+.B \-w3
+is assumed).
+When
+.B \-W
+is employed the fields will be constant width and with leading zeroes.
+.PP
+One or more
+.I files
+(processed in left to right order)
+specify the source of data to be transformed.
+A \- will specify the location of processing standard input.
+If no files are specified, the input is assumed to be from
+.I stdin.
+For ASCII input data the two data values must be in the
+first two white space separated fields and
+when both input and output are ASCII all trailing portions
+of the input line are appended to the output line.
+.PP
+Input geographic data
+(longitude and latitude) must be in DMS format when neither
+.I utm
+nor
+.I spcs
+is specified, otherwise in meters or feet (\fIfeet\fR option used).
+Input data fields must be separated by white space and not have
+imbedded white space.
+.PP
+Output data will be in tab separated fields of DMS or grid
+coordinates in meters or feet.
+.PP
+Any data after the two input values are echoed after the two
+output data values.
+.SH SEE ALSO
+.I "Cartographic Projection Procedures for the UNIX Environment\(emA User's Manual,"
+(Evenden, 1990, Open-file report 90\-284).
diff --git a/man/man1/proj.1 b/man/man1/proj.1
new file mode 100644
index 00000000..a335d55a
--- /dev/null
+++ b/man/man1/proj.1
@@ -0,0 +1,283 @@
+.\" release 4
+.nr LL 5.5i
+.ad b
+.hy 1
+.TH PROJ 1 "94/01/29 Rel. 4, Ver. BETA" "GIE"
+.SH NAME
+proj \- forward cartographic projection filter
+.br
+invproj \- inverse cartographic projection filter
+.SH SYNOPSIS
+.B proj
+[
+.B \-bceEfiIlmorsStTvVwW
+[
+.I args
+] ] [
+.B +args
+]
+file[s]
+.br
+.B invproj
+[
+.B \-bceEfiIlmorsStTwW
+[
+.I args
+] ] [
+.B +args
+]
+file[s]
+.SH DESCRIPTION
+.I Proj
+and
+.I invproj
+perform respective forward and inverse transformation of cartographic data
+to or from cartesian data with a wide range of selectable projection functions.
+.PP
+The following control parameters can appear in any order:
+.TP
+.BI \-b
+Special option for binary coordinate data input and output
+through standard input and standard output.
+Data is assumed to be in system type
+.I double
+floating point words.
+This option is to be used when
+.B proj
+is a
+.I son
+process and allows bypassing formatting operations.
+.TP
+.BI \-i
+Selects binary input only (see
+.B \-b option).
+.TP
+.BI \-I
+alternate method to specify inverse projection.
+Redundant when used with
+.B invproj.
+.TP
+.BI \-o
+Selects binary output only (see
+.B \-b option).
+.TP
+.BI \-t "a"
+.I A
+specifies a character employed as the first character to denote
+a control line to be passed through without processing.
+This option applicable to ascii input only.
+(# is the default value).
+.TP
+.BI \-e " string"
+.I String
+is an arbitrary string to be output if an error is detected during
+data transformations.
+The default value is: *\et*.
+Note that if the
+.B \-b,
+.B \-i
+or
+.B \-o
+options are employed, an error is returned as HUGE_VAL
+value for both return values.
+.TP
+.BI \-E
+causes the input coordinates to be copied to the output line
+prior to printing the converted values.
+.TP
+.BI \-l "[p|P|=|e|u]" id
+List projection identifiers with
+.B \-l,
+.B \-lp
+or
+.B \-lP (expanded)
+that can be selected with
+.B +proj.
+.BI \-l= id
+gives expanded description of projection
+.I id.
+List ellipsoid identifiers with
+.B \-le,
+that can be selected with
+.B +ellps
+or
+.B \-lu
+list of cartesian to meter conversion factors
+that can be selected with
+.B +units.
+.TP
+.BI \-r
+This options reverses the order of the
+expected input from longitude-latitude or x-y to latitude-longitude or y-x.
+.TP
+.BI \-s
+This options reverses the order of the
+output from x-y or longitude-latitude to y-x or latitude-longitude.
+.TP
+.BI \-S
+Causes estimation of
+.I meridinal
+and
+.I parallel
+scale factors,
+.I area
+scale factor and
+.I angular distortion,
+and
+.I maximum
+and
+.I minimum
+scale factors to be listed between <> for each input point.
+For conformal projections meridinal and parallel scales factors
+will be equal and angular distortion zero.
+Equal area projections will have an area factor of 1.
+.TP
+.BI \-m " mult"
+The cartesian data may be scaled by the
+.I mult
+parameter.
+When processing data in a forward projection mode the
+cartesian output values are multiplied by
+.I mult
+otherwise the input cartesian values are divided by
+.I mult
+before inverse projection.
+If the first two characters of
+.I mult
+are 1/ or 1: then the reciprocal value of
+.I mult
+is employed.
+.TP
+.BI \-f " format"
+.I Format
+is a
+.I printf
+format string to control the form of the output values.
+For inverse projections, the output will be in degrees when this option
+is employed.
+If a format is specified for inverse projection the
+output data will be in decimal degrees.
+The default format is \(``%.2f\('' for forward projection and DMS
+for inverse.
+.TP
+.BI \-[w|W] n
+.I N
+is the number of significant fractional digits to employ for
+seconds output (when the option is not specified,
+.B \-w3
+is assumed).
+When
+.B \-W
+is employed the fields will be constant width and with leading zeroes.
+.TP
+.B \-v
+causes a listing of cartographic control parameters tested for and
+used by the program to be printed prior to input data.
+Should not be used with the
+.B \-T
+option.
+.TP
+.B \-V
+This option causes an expanded annotated listing of the characteristics
+of the projected point.
+.B -v is implied with this option.
+.TP
+.BI \-T " ulow,uhi,vlow,vhi,res[,umax,vmax]"
+This option creates a set of bivariate Chebyshev polynomial
+coefficients that approximate the selected cartographic projection on
+.I stdout.
+The values
+.I low
+and
+.I hi
+denote the range of the input where the
+.I u
+or
+.I v
+prefixes apply to respective longitude-x or latitude-y
+depending upon whether a forward or inverse projection is selected.
+.I Res
+is an integer number specifying the power of 10 precision of the
+approximation.
+For example, a
+.I res
+of -3 specifies an approximation with an accuracy better than .001.
+.I Umax,
+and
+.I vmax
+specify maximum degree of the polynomials (default: 15).
+See also:
+.B fproj(1).
+.PP
+The
+.B +args
+run-line arguments are associated with cartographic parameters
+and usage varies with projection and for a complete description see
+.I "Cartographic Projection Procedures for the UNIX Environment\(emA User's Manual" )
+and supplementary documentation for Release 4.
+.PP
+Additional projection control parameters may be contained in two
+auxilliary control files:
+the first is optionally referenced with the
+.BI +init= file:id
+and the second is always processed after the name
+of the projection has been established from either the run-line
+or the contents of
+.B +init
+file.
+The environment parameter
+.B PROJ_LIB
+establishes the default directory for a file reference without
+an absolute path.
+.PP
+One or more
+.I files
+(processed in left to right order)
+specify the source of data to be transformed.
+A \- will specify the location of processing standard input.
+If no files are specified, the input is assumed to be from
+.I stdin.
+For ASCII input data the two data values must be in the
+first two white space separated fields and
+when both input and output are ASCII all trailing portions
+of the input line are appended to the output line.
+.PP
+Input geographic data
+(longitude and latitude) must be in DMS format and input
+cartesian data must be in units consistent with the ellipsoid
+major axis or sphere radius units.
+Output geographic coordinates will be in DMS
+(if the
+.B \-w
+switch is not employed) and precise to 0.001"
+with trailing, zero-valued minute-second fields deleted.
+.SH EXAMPLE
+The following script
+.RS 5
+ \f(CWproj +proj=utm +lon_0=112w -r <<EOF
+ 45d15'33.1"	111.5W
+ 45d15.551666667N	-111d30
+ +45.25919444444	111d30'000w
+ EOF\fR
+.RE
+will perform UTM forward projection with a standard UTM
+central meridian nearest longitude 112\(deW.
+The geographic values of this example are equivalent and meant
+as examples of various forms of DMS input.
+The x\-y output data will appear as three lines of:
+.RS 5
+ \f(CW460769.27	5011648.45
+.RE
+.SH SEE ALSO
+.I "Cartographic Projection Procedures for the UNIX Environment\(emA User's Manual,"
+(Evenden, 1990, Open-file report 90\-284).
+.br
+.I "Map Projections Used by the U. S. Geological Survey"
+(Snyder, 1984,
+USGS Bulletin 1532).
+.br
+.I "Map Projections\(emA Working Manual"
+(Synder, 1988, USGS Prof. Paper 1395).
+.br
+.I "An Album of Map Projections"
+(Snyder & Voxland, 1989, USGS Prof. Paper 1453).
diff --git a/man/man3/pj_init.3 b/man/man3/pj_init.3
new file mode 100644
index 00000000..d6d8e952
--- /dev/null
+++ b/man/man3/pj_init.3
@@ -0,0 +1,85 @@
+.\" @(#)pj_init.3 - 4.1
+.nr LL 5.5i
+.TH PJ_INIT 3U "92/11/08 Rel. 4, Ver. BETA" "GIE"
+.ad b
+.hy 1
+.SH NAME
+pj_init \- initialize cartographic projection
+.br
+pj_fwd \- forward cartographic projection
+.br
+pj_inv \- inverse cartographic projection
+.br
+pj_free \- de-initialize projection
+.SH SYNOPSIS
+.nf
+#include <projects.h>
+
+PJ *pj_init(int argc, char **argv)
+
+UV pj_fwd(UV val, PJ *proj)
+
+UV pj_inv(UV val, PJ *proj)
+
+void pj_free(PJ *proj)
+
+.SH DESCRIPTION
+Procedure \fBpj_init\fR selects and initializes a cartographic projection
+with its argument control parameters.
+\fBArgc\fR is the number of elements in the array of control strings
+\fBargv\fR that each contain individual cartographic control keyword
+assignments (\f(CW+\fR \fBproj\fR arguments).
+The list must contain at least the \fBproj=\fIprojection\fR and
+Earth's radius or elliptical parameters.
+If the initialization of the projection is successful a valid
+address is returned otherwise a NULL value.
+
+Once initialization is performed either forward or inverse
+projections can be performed with the returned value of \fBpj_init\fR
+used as the argument \fBproj\fR.
+The argument structure \fBUV\fR values \fBu\fR and \fBv\fR contain
+respective longitude and latitude or x and y.
+Latitude and longitude are in radians.
+If a projection operation fails, both elements of \fBUV\fR are
+set to HUGE_VAL (defined in \fImath.h\fR).
+
+\fBNote:\fR all projections have a forward mode, but some do not have
+an inverse projection.
+If the projection does not have an inverse the PJ structure element
+\fIinv\fR will be NULL.
+
+Memory associated with the projection may be freed with \fBpj_free\fR.
+.SH EXAMPLE
+The following program reads latitude and longitude values in decimal
+degress, performs Mercator projection with a Clarke 1866 ellipsoid and
+a 33\(de latitude of true scale and prints the projected
+cartesian values in meters:
+.nf
+\f(CW
+#include <projects.h>
+main(int argc, char **argv) {
+	char *args[] = { "proj=merc", "ellps=clrk66", "lat_ts=33" };
+	UV p;
+	PJ *pj;
+
+	if (!(pj = pj_init(3, args)))
+	   exit(1);
+	while (scanf("%lf %lf", &p.v, &p.u) == 2) {
+	   p.u *= DEG_TO_RAD;
+	   p.v *= DEG_TO_RAD;
+	   p = pj_fwd(p, pj);
+	   printf("%.2f\et%.2f\en", p.u, p.v);
+	}
+	exit(0);
+} \fR
+.br
+.fi
+.SH LIBRARY
+libpj.a \- library of projections and support procedures
+.SH SEE ALSO
+.B proj(1U),
+.br
+.I "Cartographic Projection Procedures for the UNIX Environment\(emA User's Manual,"
+(Evenden, 1990, Open-file report 90\-284).
+.SH AUTHOR/MAINTENANCE
+Gerald I. Evenden, USGS, Woods Hole, MA 02543