diff options
Diffstat (limited to 'docs/source/usage/apps/cs2cs.rst')
| -rw-r--r-- | docs/source/usage/apps/cs2cs.rst | 264 |
1 files changed, 154 insertions, 110 deletions
diff --git a/docs/source/usage/apps/cs2cs.rst b/docs/source/usage/apps/cs2cs.rst index 675379ef..ba77aadf 100644 --- a/docs/source/usage/apps/cs2cs.rst +++ b/docs/source/usage/apps/cs2cs.rst @@ -4,140 +4,184 @@ cs2cs ================================================================================ +.. only:: html -``cs2cs`` performs transformation between the source and destination cartographic coordinate system -on a set of input points. The coordinate system transformation can include translation between -projected and geographic coordinates as well as the application of datum shifts. - + Cartographic coordinate system filter. Synopsis ******** -:: - - cs2cs [ -eEfIlrstvwW [ args ] ] [ +opts[=arg] ] [ +to [+opts[=arg]] ] file[s] + **cs2cs** [ **-eEfIlrstvwW** [ args ] ] [ *+opts[=arg]* ] [ +to [*+opts[=arg]*] ] file[s] Description *********** + +:program:`cs2cs` performs transformation between the source and destination +cartographic coordinate system on a set of input points. The coordinate +system transformation can include translation between projected and +geographic coordinates as well as the application of datum shifts. + The following control parameters can appear in any order: -:: +.. program:: cs2cs + +.. option:: -I + + method to specify inverse translation, convert from *+to* coordinate system to + the primary coordinate system defined. + +.. option:: -t<a> + + 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). + +.. option:: -e <string> + + String is an arbitrary string to be output if an error is detected during + data transformations. The default value is: *\t*. Note that if the -b, -i + or -o options are employed, an error is returned as HUGE_VAL value for both + return values. + +.. option:: -E + + causes the input coordinates to be copied to the output line prior to + printing the converted values. + +.. option:: -l<[=id]> + + List projection identifiers that can be selected with *+proj*. ``cs2cs -l=id`` + gives expanded description of projection id, e.g. ``cs2cs -l=merc``. + +.. option:: -lp + + List of all projection id that can be used with the *+proj* parameter. + Equivalent to ``cs2cs -l``. + +.. option:: -lP + + Expanded description of all projections that can be used with the *+proj* + parameter. + +.. option:: -le + + List of all ellipsoids that can be selected with the *+ellps* parameters. + +.. option:: -lu + + List of all distance units that can be selected with the *+units* parameter. + +.. option:: -ld + + List of datums that can be selected with the *+datum* parameter. - -I method to specify inverse translation, convert from +to coordinate system to the - primary coordinate system defined. - - -ta 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). - - -e string - String is an arbitrary string to be output if an error is detected during data - transformations. The default value is: *\t*. Note that if the -b, -i or -o - options are employed, an error is returned as HUGE_VAL value for both - return values. - - -E causes the input coordinates to be copied to the output line prior to printing the - converted values. - - -l[p|P|=|e|u|d]id - List projection identifiers with -l, -lp or -lP (expanded) that can be selected - with +proj. -l=id gives expanded description of projection id. List - ellipsoid identifiers with -le, that can be selected with +ellps,-lu list of - cartesian to meter conversion factors that can be selected with +units or -ld - list of datums that can be selected with +datum. - - -r This options reverses the order of the expected input from longitude-latitude or - x-y to latitude-longitude or y-x. - - -s This options reverses the order of the output from x-y or longitude-latitude to - y-x or latitude-longitude. - - -f format - Format is a 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 deci- - mal degrees. The default format is "%.2f" for forward projection and DMS for - inverse. - - -[w|W]n - N is the number of significant fractional digits to employ for seconds output (when - the option is not specified, -w3 is assumed). When -W is employed the fields - will be constant width and with leading zeroes. - - -v causes a listing of cartographic control parameters tested for and used by the - program to be printed prior to input data. - -The ``+args`` run-line arguments are associated with cartographic parameters. Usage varies with -projection and for a complete description consult the `projection pages <../projections/index.html>`_ - -The cs2cs program requires two coordinate system -definitions. The first (or primary is defined -based on all projection parameters not appearing -after the +to argument. All projection parameters -appearing after the ``+to`` argument are considered -the definition of the second coordinate -system. If there is no second coordinate system -defined, a geographic coordinate system based on -the datum and ellipsoid of the source coordinate -system is assumed. Note that the source and -destination coordinate system can both be projections, -both be geographic, or one of each and -may have the same or different datums. - -Additional projection control parameters may be -contained in two auxiliary control files: the -first is optionally referenced with the -``+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 ``+init`` file. The environment parameter -PROJ_LIB establishes the default directory for a -file reference without an absolute path. This -is also used for supporting files like datum -shift files. - -One or more 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 stdin. -For 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. - -Input geographic data (longitude and latitude) -must be in DMS or decimal degrees format and -input cartesian data must be in units consistent -with the ellipsoid major axis or sphere radius -units. Output geographic coordinates will normally -be in DMS format (use ``-f %.12f`` for decimal -degrees with 12 decimal places), while projected -(cartesian) coordinates will be in linear +.. option:: -r + + This options reverses the order of the expected input from + longitude-latitude or x-y to latitude-longitude or y-x. + +.. option:: -s + + This options reverses the order of the output from x-y or longitude-latitude + to y-x or latitude-longitude. + +.. option:: -f <format> + + Format is a 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 deci- mal degrees. The default format is "%.2f" for forward + projection and DMS for inverse. + +.. option:: -[w|W]<n> + + N is the number of significant fractional digits to employ for seconds + output (when the option is not specified, -w3 is assumed). When -W is + employed the fields will be constant width and with leading zeroes. + +.. option:: -v + + causes a listing of cartographic control parameters tested for and used by + the program to be printed prior to input data. + + +.. only:: man + + The *+args* run-line arguments are associated with cartographic + parameters. + +.. only:: html + + The *+args* run-line arguments are associated with cartographic + parameters. Usage varies with projection and for a complete description + consult the :ref:`projection pages <projections>`. + +The :program:`cs2cs` program requires two coordinate system definitions. The first (or +primary is defined based on all projection parameters not appearing after the +*+to* argument. All projection parameters appearing after the *+to* argument +are considered the definition of the second coordinate system. If there is no +second coordinate system defined, a geographic coordinate system based on the +datum and ellipsoid of the source coordinate system is assumed. Note that the +source and destination coordinate system can both be projections, both be +geographic, or one of each and may have the same or different datums. + +Additional projection control parameters may be contained in two auxiliary +control files: the first is optionally referenced with the +*+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 +*+init* file. The environment parameter PROJ_LIB establishes the default +directory for a file reference without an absolute path. This is also used +for supporting files like datum shift files. + +One or more 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 stdin. +For 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. + +Input geographic data (longitude and latitude) must be in DMS or decimal +degrees format and input cartesian data must be in units consistent with the +ellipsoid major axis or sphere radius units. Output geographic coordinates will +normally be in DMS format (use ``-f %.12f`` for decimal degrees with 12 decimal +places), while projected (cartesian) coordinates will be in linear (meter, feet) units. Example ******* + The following script :: - cs2cs +proj=latlong +datum=NAD83 - +to +proj=utm +zone=10 +datum=NAD27 - -r <<EOF - 45d15'33.1" 111.5W - 45d15.551666667N -111d30 - +45.25919444444 111d30'000w - EOF - -will transform the input NAD83 geographic coordinates into NAD27 -coordinates in the UTM projection with zone 10 selected. The geographic -values of this example are equivalent and meant as examples of various forms of DMS input. + cs2cs +proj=latlong +datum=NAD83 +to +proj=utm +zone=10 +datum=NAD27 -r + <<EOF 45d15'33.1" 111.5W 45d15.551666667N -111d30 +45.25919444444 + 111d30'000w EOF + +will transform the input NAD83 geographic coordinates into NAD27 coordinates in +the UTM projection with zone 10 selected. 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: :: 1402285.99 5076292.42 0.000 +.. only:: man + + See also + ******** + + **proj(1)**, **cct(1)**, **geod(1)**, **gie(1)** + + Bugs + **** + + A list of know bugs can be found at http://github.com/OSGeo/proj.4/issues + where new bug reports can be submitted to. + + Home page + ********* + http://proj4.org/ |