cs2cs(1) - f39

1CS2CS(1)                             PROJ                             CS2CS(1)
2
3
4

NAME

6       cs2cs - Cartographic coordinate system filter
7

SYNOPSIS

9          cs2cs [-eEfIlrstvwW [args]]
10            [[--area <name_or_code>] | [--bbox <west_long,south_lat,east_long,north_lat>]]
11            [--authority <name>] [--3d]
12            [--accuracy <accuracy>] [--only-best[=yes|=no]] [--no-ballpark]
13            ([+opt[=arg] ...] [+to +opt[=arg] ...] | {source_crs} {target_crs})
14            file ...
15
16
17          where  {source_crs}  or {target_crs} is one of the possibilities ac‐
18          cepted by proj_create(), provided it expresses a CRS
19
20          • a proj-string,
21
22          • a WKT string,
23
24          • an object code  (like  "EPSG:4326",  "urn:ogc:def:crs:EPSG::4326",
25            "urn:ogc:def:coordinateOperation:EPSG::1671"),
26
27          • an  Object  name.  e.g  "WGS 84", "WGS 84 / UTM zone 31N". In that
28            case as uniqueness is not guaranteed, heuristics  are  applied  to
29            determine the appropriate best match.
30
31          • a CRS name and a coordinate epoch, separated with '@'. For example
32            "ITRF2014@2025.0". (added in 9.2)
33
34          • a OGC URN combining references for compound  coordinate  reference
35            systems  (e.g  "urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717"  or
36            custom abbreviated syntax "EPSG:2393+5717"),
37
38          • a OGC URN combining references for references for projected or de‐
39            rived CRSs e.g. for Projected 3D CRS "UTM zone 31N / WGS 84 (3D)":
40            "‐
41            urn:ogc:def:crs,crs:EPSG::4979,cs:PROJ::ENh,coordinateOpera‐
42            tion:EPSG::16031" (added in 6.2)
43
44          • a OGC URN combining references for concatenated  operations  (e.g.
45            "‐
46            urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,co‐
47            ordinateOperation:EPSG::1618")
48
49          • a      PROJJSON      string.      The     jsonschema     is     at
50            https://proj.org/schemas/v0.4/projjson.schema.json (added in 6.2)
51
52          • a compound CRS made from two object names separated with  "  +  ".
53            e.g. "WGS 84 + EGM96 height" (added in 7.1)
54
55          New in version 6.0.0.
56
57
58          NOTE:
59              before  7.0.1, it was needed to add +to between {source_crs} and
60              {target_crs} when adding a filename
61

DESCRIPTION

63       cs2cs performs transformation between the source and destination carto‐
64       graphic coordinate reference system on a set of input points. The coor‐
65       dinate reference system transformation can include translation  between
66       projected  and geographic coordinates as well as the application of da‐
67       tum shifts.
68
69       The following control parameters can appear in any order:
70
71       -I     Method to specify inverse translation, convert from +to  coordi‐
72              nate system to the primary coordinate system defined.
73
74       -t<a>  Where a specifies a character employed as the first character to
75              denote a control line to be passed through  without  processing.
76              This  option  applicable  to ASCII input only. (# is the default
77              value).
78
79       -d <n> New in version 5.2.0.
80
81
82              Specify the number of decimals to round to in the output.
83
84       -e <string>
85              Where string is an arbitrary string to be output if an error  is
86              detected  during  data  transformations.  The default value is a
87              three character string: *\t*.
88
89       -E     Causes the input coordinates to be copied  to  the  output  line
90              prior to printing the converted values.
91
92       -l<[=id]>
93              List  projection  identifiers  that  can be selected with +proj.
94              cs2cs -l=id gives expanded description of  projection  id,  e.g.
95              cs2cs -l=merc.
96
97       -lp    List of all projection id that can be used with the +proj param‐
98              eter.  Equivalent to cs2cs -l.
99
100       -lP    Expanded description of all projections that can  be  used  with
101              the +proj parameter.
102
103       -le    List  of all ellipsoids that can be selected with the +ellps pa‐
104              rameters.
105
106       -lu    List of all distance units that can be selected with the  +units
107              parameter.
108
109       -r     This options reverses the order of the first two expected inputs
110              from that specified by the CRS to the opposite order.  The third
111              coordinate, typically height, remains third.
112
113       -s     This  options  reverses the order of the first two expected out‐
114              puts from that specified by the CRS to the opposite order.   The
115              third coordinate, typically height, remains third.
116
117       -f <format>
118              Where  format  is  a printf format string to control the form of
119              the output values.  For inverse projections, the output will  be
120              in  degrees  when this option is employed. If a format is speci‐
121              fied for inverse projection the output data will be  in  decimal
122              degrees. The default format is "%.2f" for forward projection and
123              DMS for inverse.
124
125       -w<n>  Where n is the number of significant fractional digits to employ
126              for seconds output (when the option is not specified, -w3 is as‐
127              sumed).
128
129       -W<n>  Where n is the number of significant fractional digits to employ
130              for  seconds output. When -W is employed the fields will be con‐
131              stant width with leading zeroes. Valid range: -W0 through -W8.
132
133       -v     Causes a listing of cartographic control parameters  tested  for
134              and used by the program to be printed prior to input data.
135
136       --area <name_or_code>
137              New in version 8.0.0.
138
139
140              Specify  an  area  of  interest to restrict the results when re‐
141              searching coordinate operations between 2 CRS. The area  of  in‐
142              terest  can  be  specified  either as a name (e.g "Denmark - on‐
143              shore") or a AUTHORITY:CODE (EPSG:3237)
144
145              This option is mutually exclusive with --bbox.
146
147       --bbox <west_long,south_lat,east_long,north_lat>
148              New in version 8.0.0.
149
150
151              Specify an area of interest to restrict  the  results  when  re‐
152              searching  coordinate  operations between 2 CRS. The area of in‐
153              terest is specified as a bounding box  with  geographic  coordi‐
154              nates,  expressed  in  degrees  in a unspecified geographic CRS.
155              west_long and east_long should be in the [-180,180]  range,  and
156              south_lat  and north_lat in the [-90,90]. west_long is generally
157              lower than east_long, except in the case where the area  of  in‐
158              terest crosses the antimeridian.
159
160       --only-best[=yes|=no]
161              New in version 9.2.0.
162
163
164              Force  cs2cs  to only use the best transformation known by PROJ.
165              cs2cs will return an error if a grid needed for the best  trans‐
166              formation is missing.
167
168              Best  transformation  should  be understood as the most accurate
169              transformation available among all relevant  for  the  point  to
170              transform,  and  if  all  known  grids  required to perform such
171              transformation were accessible (either locally or  through  net‐
172              work).
173
174              Note that the default value for this option can be also set with
175              the PROJ_ONLY_BEST_DEFAULT environment  variable,  or  with  the
176              only_best_default  setting  of proj.ini (--only-best when speci‐
177              fied overrides such default value).
178
179       --no-ballpark
180              New in version 8.0.0.
181
182
183              Disallow any  coordinate  operation  that  is,  or  contains,  a
184              Ballpark transformation
185
186       --accuracy <accuracy>
187              New in version 8.0.0.
188
189
190              Sets the minimum desired accuracy for candidate coordinate oper‐
191              ations.
192
193       --authority <name>
194              New in version 8.0.0.
195
196
197              This option can be used to restrict the authority of  coordinate
198              operations  looked up in the database. When not specified, coor‐
199              dinate operations from any authority will be searched, with  the
200              restrictions  set in the authority_to_authority_preference data‐
201              base table related to the authority  of  the  source/target  CRS
202              themselves.   If authority is set to any, then coordinate opera‐
203              tions from any authority will be  searched  If  authority  is  a
204              non-empty  string  different  of any, then coordinate operations
205              will be searched only in that authority namespace (e.g EPSG).
206
207              This option is mutually exclusive with --bbox.
208
209       --3d   New in version 9.1.
210
211
212              "Promote" 2D CRS(s) to their 3D version, where the vertical axis
213              is  the ellipsoidal height in metres, using the ellipsoid of the
214              base geodetic CRS.  Depending on PROJ versions and the exact na‐
215              ture  of  the CRS involved, especially before PROJ 9.1, a mix of
216              2D and 3D CRS could lead to 2D or 3D  transformations.  Starting
217              with  PROJ  9.1, both CRS need to be 3D for vertical transforma‐
218              tion to possibly happen.
219
220       The +opt run-line arguments are associated  with  cartographic  parame‐
221       ters.
222
223       The  cs2cs program requires two coordinate reference system (CRS) defi‐
224       nitions. The first (or primary is defined based on all  projection  pa‐
225       rameters  not  appearing after the +to argument. All projection parame‐
226       ters appearing after the +to argument are considered the definition  of
227       the  second  CRS.  If  there is no second CRS defined, a geographic CRS
228       based on the datum and ellipsoid of the source  CRS  is  assumed.  Note
229       that  the  source and destination CRS can both of same or different na‐
230       ture (geographic, projected, compound CRS), or one of each and may have
231       the same or different datums.
232
233       When  using a WKT definition or a AUTHORITY:CODE, the axis order of the
234       CRS will be enforced. So for example  if  using  EPSG:4326,  the  first
235       value expected (or returned) will be a latitude.
236
237       Internally, cs2cs uses the proj_create_crs_to_crs() function to compute
238       the appropriate coordinate operation, so implementation details of this
239       function directly impact the results returned by the program.
240
241       The  environment  parameter PROJ_DATA establishes the directory for re‐
242       source files (database, datum shift grids, etc.)
243
244       One or more files (processed in left to right order) specify the source
245       of  data to be transformed. A - will specify the location of processing
246       standard input. If no files are specified, the input is assumed  to  be
247       from  stdin.   For  input data the two data values must be in the first
248       two white space separated fields and when both  input  and  output  are
249       ASCII  all trailing portions of the input line are appended to the out‐
250       put line.
251
252       Input geographic data (longitude and latitude) must be in DMS or  deci‐
253       mal degrees format and input cartesian data must be in units consistent
254       with the ellipsoid major axis or sphere radius units. Output geographic
255       coordinates  will  normally  be in DMS format (use -f %.12f for decimal
256       degrees with 12 decimal places), while  projected  (cartesian)  coordi‐
257       nates will be in linear (meter, feet) units.
258
259   Use of remote grids
260       New in version 7.0.0.
261
262
263       If  the  PROJ_NETWORK environment variable is set to ON, cs2cs will at‐
264       tempt to use remote grids stored  on  CDN  (Content  Delivery  Network)
265       storage, when they are not available locally.
266
267       More details are available in the Network capabilities section.
268

EXAMPLES

270   Using PROJ strings
271       The following script
272
273          cs2cs +proj=latlong +datum=NAD83 +to +proj=utm +zone=10 +datum=NAD27 -r <<EOF
274          45°15'33.1" 111.5W
275          45d15.551666667N -111d30
276          +45.25919444444 111d30'000w
277          EOF
278
279       will  transform the input NAD83 geographic coordinates into NAD27 coor‐
280       dinates in the UTM projection with zone  10  selected.  The  geographic
281       values  of this example are equivalent and meant as examples of various
282       forms of DMS input.  The x-y output data will appear as three lines of:
283
284          1402285.93  5076292.58 0.00
285
286       To get those exact values, you have need to have all current grids  in‐
287       stalled     (in     that     instance    the    NADCON5    us_noaa_nad‐
288       con5_nad27_nad83_1986_conus.tif grid) locally or use  networking  capa‐
289       bilities mentioned above.
290
291       To  make sure you will get the optimal result, you may add --only-best.
292       Assuming the above mentioned grid is not available,
293
294          echo -111.5 45.25919444444 | cs2cs --only-best +proj=latlong +datum=NAD83 +to +proj=utm +zone=10 +datum=NAD27
295
296       would return:
297
298          Attempt to use coordinate operation axis order change (2D) + Inverse of NAD27 to NAD83 (7) + axis order change (2D) + UTM zone 10N failed. Grid us_noaa_nadcon5_nad27_nad83_1986_conus.tif is not available. Consult https://proj.org/resource_files.html for guidance.
299          *   * inf
300
301       Otherwise, if you don't have the grid available and you  don't  specify
302       --only-best:
303
304          echo -111.5 45.25919444444 | cs2cs --only-best +proj=latlong +datum=NAD83 +to +proj=utm +zone=10 +datum=NAD27
305
306       would return:
307
308          1402224.57  5076275.42 0.00
309
310       which  is the result when the NAD27 and NAD83 datums are dealt as iden‐
311       tical, which is an approximation at a level of several tens of metres.
312
313   Using EPSG CRS codes
314       Transforming from WGS 84 latitude/longitude (in that order) to UTM Zone
315       31N/WGS 84
316
317          cs2cs EPSG:4326 EPSG:32631 <<EOF
318          45N 2E
319          EOF
320
321       outputs
322
323          421184.70   4983436.77 0.00
324
325   Using EPSG CRS names
326       Transforming  from WGS 84 latitude/longitude (in that order) with EGM96
327       height to UTM Zone 31N/WGS 84 with WGS84 ellipsoidal height
328
329          echo 45 2 0 | cs2cs "WGS 84 + EGM96 height" "WGS 84 / UTM zone 31N" --3d
330
331       outputs
332
333          421184.70   4983436.77 50.69
334
335       NOTE:
336          To get those exact values, you have need to have the EGM96 grid  in‐
337          stalled locally or use networking capabilities mentioned above.
338

BUGS

343       A      list      of      known     bugs     can     be     found     at
344       https://github.com/OSGeo/PROJ/issues where new bug reports can be  sub‐
345       mitted to.
346

HOME PAGE

348       https://proj.org/
349

AUTHOR

351       Frank Warmerdam
352

COPYRIGHT

354       1983-2023
355
356
357
358
3599.2.1                             Jun 1, 2023                         CS2CS(1)