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

DESCRIPTION

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

EXAMPLES

236   Using PROJ strings
237       The following script
238
239          cs2cs +proj=latlong +datum=NAD83 +to +proj=utm +zone=10 +datum=NAD27 -r <<EOF
240          45°15'33.1" 111.5W
241          45d15.551666667N -111d30
242          +45.25919444444 111d30'000w
243          EOF
244
245       will  transform the input NAD83 geographic coordinates into NAD27 coor‐
246       dinates in the UTM projection with zone  10  selected.  The  geographic
247       values  of this example are equivalent and meant as examples of various
248       forms of DMS input.  The x-y output data will appear as three lines of:
249
250          1402293.44  5076292.68 0.00
251
252   Using EPSG CRS codes
253       Transforming from WGS 84 latitude/longitude (in that order) to UTM Zone
254       31N/WGS 84
255
256          cs2cs EPSG:4326 EPSG:32631 <<EOF
257          45N 2E
258          EOF
259
260       outputs
261
262          421184.70   4983436.77 0.00
263
264   Using EPSG CRS names
265       Transforming  from WGS 84 latitude/longitude (in that order) with EGM96
266       height to UTM Zone 31N/WGS 84 with WGS84 ellipsoidal height
267
268          echo 45 2 0 | cs2cs "WGS 84 + EGM96 height" "WGS 84 / UTM zone 31N"
269
270       outputs
271
272          421184.70   4983436.77 50.69
273

SEE ALSO

275       proj(1), cct(1), geod(1), gie(1), projinfo(1), projsync(1)
276

BUGS

278       A     list     of     known     bugs     can      be      found      at
279       https://github.com/OSGeo/PROJ/issues  where new bug reports can be sub‐
280       mitted to.
281

HOME PAGE

283       https://proj.org/
284

AUTHOR

286       Frank Warmerdam
287
289       1983-2021
290
291
292
293
2948.2.0                             Nov 1, 2021                         CS2CS(1)
Impressum