Coverage Report

Created: 2025-06-09 08:44

/src/gdal/proj/include/proj/coordinateoperation.hpp
Line
Count
Source
1
/******************************************************************************
2
 *
3
 * Project:  PROJ
4
 * Purpose:  ISO19111:2019 implementation
5
 * Author:   Even Rouault <even dot rouault at spatialys dot com>
6
 *
7
 ******************************************************************************
8
 * Copyright (c) 2018, Even Rouault <even dot rouault at spatialys dot com>
9
 *
10
 * Permission is hereby granted, free of charge, to any person obtaining a
11
 * copy of this software and associated documentation files (the "Software"),
12
 * to deal in the Software without restriction, including without limitation
13
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
14
 * and/or sell copies of the Software, and to permit persons to whom the
15
 * Software is furnished to do so, subject to the following conditions:
16
 *
17
 * The above copyright notice and this permission notice shall be included
18
 * in all copies or substantial portions of the Software.
19
 *
20
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
21
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
23
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
25
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
26
 * DEALINGS IN THE SOFTWARE.
27
 ****************************************************************************/
28
29
#ifndef COORDINATEOPERATION_HH_INCLUDED
30
#define COORDINATEOPERATION_HH_INCLUDED
31
32
#include <memory>
33
#include <string>
34
#include <utility>
35
#include <vector>
36
37
#include "common.hpp"
38
#include "io.hpp"
39
#include "metadata.hpp"
40
41
#include "proj.h"
42
43
NS_PROJ_START
44
45
namespace crs {
46
class CRS;
47
using CRSPtr = std::shared_ptr<CRS>;
48
using CRSNNPtr = util::nn<CRSPtr>;
49
50
class DerivedCRS;
51
class ProjectedCRS;
52
} // namespace crs
53
54
namespace io {
55
class JSONParser;
56
} // namespace io
57
58
namespace coordinates {
59
class CoordinateMetadata;
60
using CoordinateMetadataPtr = std::shared_ptr<CoordinateMetadata>;
61
using CoordinateMetadataNNPtr = util::nn<CoordinateMetadataPtr>;
62
} // namespace coordinates
63
64
/** osgeo.proj.operation namespace
65
66
  \brief Coordinate operations (relationship between any two coordinate
67
  reference systems).
68
69
  This covers Conversion, Transformation,
70
  PointMotionOperation or ConcatenatedOperation.
71
*/
72
namespace operation {
73
74
// ---------------------------------------------------------------------------
75
76
/** \brief Grid description */
77
struct GridDescription {
78
    std::string shortName;   /**< Grid short filename */
79
    std::string fullName;    /**< Grid full path name (if found) */
80
    std::string packageName; /**< Package name (or empty) */
81
    std::string url;         /**< Grid URL (if packageName is empty), or package
82
                                    URL (or empty) */
83
    bool directDownload;     /**< Whether url can be fetched directly. */
84
    /** Whether the grid is released with an open license. */
85
    bool openLicense;
86
    bool available; /**< Whether GRID is available. */
87
88
    //! @cond Doxygen_Suppress
89
31.1k
    bool operator<(const GridDescription &other) const {
90
31.1k
        return shortName < other.shortName;
91
31.1k
    }
92
93
    PROJ_DLL GridDescription();
94
    PROJ_DLL ~GridDescription();
95
    PROJ_DLL GridDescription(const GridDescription &);
96
    PROJ_DLL GridDescription(GridDescription &&) noexcept;
97
    //! @endcond
98
};
99
100
// ---------------------------------------------------------------------------
101
102
class CoordinateOperation;
103
/** Shared pointer of CoordinateOperation */
104
using CoordinateOperationPtr = std::shared_ptr<CoordinateOperation>;
105
/** Non-null shared pointer of CoordinateOperation */
106
using CoordinateOperationNNPtr = util::nn<CoordinateOperationPtr>;
107
108
// ---------------------------------------------------------------------------
109
110
class CoordinateTransformer;
111
/** Shared pointer of CoordinateTransformer */
112
using CoordinateTransformerPtr = std::unique_ptr<CoordinateTransformer>;
113
/** Non-null shared pointer of CoordinateTransformer */
114
using CoordinateTransformerNNPtr = util::nn<CoordinateTransformerPtr>;
115
116
/** \brief Coordinate transformer.
117
 *
118
 * Performs coordinate transformation of coordinate tuplies.
119
 *
120
 * @since 9.3
121
 */
122
class PROJ_GCC_DLL CoordinateTransformer {
123
  public:
124
    //! @cond Doxygen_Suppress
125
    PROJ_DLL ~CoordinateTransformer();
126
    //! @endcond
127
128
    PROJ_DLL PJ_COORD transform(PJ_COORD coord);
129
130
  protected:
131
    PROJ_FRIEND(CoordinateOperation);
132
133
    PROJ_INTERNAL CoordinateTransformer();
134
135
    PROJ_INTERNAL static CoordinateTransformerNNPtr
136
    create(const CoordinateOperationNNPtr &op, PJ_CONTEXT *ctx);
137
138
  private:
139
    PROJ_OPAQUE_PRIVATE_DATA
140
    INLINED_MAKE_UNIQUE
141
    CoordinateTransformer &
142
    operator=(const CoordinateTransformer &other) = delete;
143
};
144
145
// ---------------------------------------------------------------------------
146
147
class Transformation;
148
/** Shared pointer of Transformation */
149
using TransformationPtr = std::shared_ptr<Transformation>;
150
/** Non-null shared pointer of Transformation */
151
using TransformationNNPtr = util::nn<TransformationPtr>;
152
153
/** \brief Abstract class for a mathematical operation on coordinates.
154
 *
155
 * A mathematical operation:
156
 * <ul>
157
 * <li>on coordinates that transforms or converts them from one coordinate
158
 * reference system to another coordinate reference system</li>
159
 * <li>or that describes the change of coordinate values within one coordinate
160
 * reference system due to the motion of the point between one coordinate epoch
161
 * and another coordinate epoch.</li>
162
 * </ul>
163
 * Many but not all coordinate operations (from CRS A to CRS B) also uniquely
164
 * define the inverse coordinate operation (from CRS B to CRS A). In some cases,
165
 * the coordinate operation method algorithm for the inverse coordinate
166
 * operation is the same as for the forward algorithm, but the signs of some
167
 * coordinate operation parameter values have to be reversed. In other cases,
168
 * different algorithms are required for the forward and inverse coordinate
169
 * operations, but the same coordinate operation parameter values are used. If
170
 * (some) entirely different parameter values are needed, a different coordinate
171
 * operation shall be defined.
172
 *
173
 * \remark Implements CoordinateOperation from \ref ISO_19111_2019
174
 */
175
class PROJ_GCC_DLL CoordinateOperation : public common::ObjectUsage,
176
                                         public io::IPROJStringExportable,
177
                                         public io::IJSONExportable {
178
  public:
179
    //! @cond Doxygen_Suppress
180
    PROJ_DLL ~CoordinateOperation() override;
181
    //! @endcond
182
183
    PROJ_DLL const util::optional<std::string> &operationVersion() const;
184
    PROJ_DLL const std::vector<metadata::PositionalAccuracyNNPtr> &
185
    coordinateOperationAccuracies() const;
186
187
    PROJ_DLL const crs::CRSPtr sourceCRS() const;
188
    PROJ_DLL const crs::CRSPtr targetCRS() const;
189
    PROJ_DLL const crs::CRSPtr &interpolationCRS() const;
190
    PROJ_DLL const util::optional<common::DataEpoch> &
191
    sourceCoordinateEpoch() const;
192
    PROJ_DLL const util::optional<common::DataEpoch> &
193
    targetCoordinateEpoch() const;
194
195
    PROJ_DLL CoordinateTransformerNNPtr
196
    coordinateTransformer(PJ_CONTEXT *ctx) const;
197
198
    /** \brief Return the inverse of the coordinate operation.
199
     *
200
     * \throw util::UnsupportedOperationException if inverse is not available
201
     */
202
    PROJ_DLL virtual CoordinateOperationNNPtr inverse() const = 0;
203
204
    /** \brief Return grids needed by an operation. */
205
    PROJ_DLL virtual std::set<GridDescription>
206
    gridsNeeded(const io::DatabaseContextPtr &databaseContext,
207
                bool considerKnownGridsAsAvailable) const = 0;
208
209
    PROJ_DLL bool
210
    isPROJInstantiable(const io::DatabaseContextPtr &databaseContext,
211
                       bool considerKnownGridsAsAvailable) const;
212
213
    PROJ_DLL bool hasBallparkTransformation() const;
214
215
    PROJ_DLL bool requiresPerCoordinateInputTime() const;
216
217
    PROJ_DLL static const std::string OPERATION_VERSION_KEY;
218
219
    PROJ_DLL CoordinateOperationNNPtr normalizeForVisualization() const;
220
221
    PROJ_PRIVATE :
222
        //! @cond Doxygen_Suppress
223
        PROJ_FOR_TEST CoordinateOperationNNPtr
224
        shallowClone() const;
225
    //! @endcond
226
227
  protected:
228
    PROJ_INTERNAL CoordinateOperation();
229
    PROJ_INTERNAL CoordinateOperation(const CoordinateOperation &other);
230
231
    PROJ_FRIEND(crs::DerivedCRS);
232
    PROJ_FRIEND(io::AuthorityFactory);
233
    PROJ_FRIEND(CoordinateOperationFactory);
234
    PROJ_FRIEND(ConcatenatedOperation);
235
    PROJ_FRIEND(io::WKTParser);
236
    PROJ_FRIEND(io::JSONParser);
237
    PROJ_INTERNAL void
238
    setWeakSourceTargetCRS(std::weak_ptr<crs::CRS> sourceCRSIn,
239
                           std::weak_ptr<crs::CRS> targetCRSIn);
240
    PROJ_INTERNAL void setCRSs(const crs::CRSNNPtr &sourceCRSIn,
241
                               const crs::CRSNNPtr &targetCRSIn,
242
                               const crs::CRSPtr &interpolationCRSIn);
243
    PROJ_INTERNAL void
244
    setCRSsUpdateInverse(const crs::CRSNNPtr &sourceCRSIn,
245
                         const crs::CRSNNPtr &targetCRSIn,
246
                         const crs::CRSPtr &interpolationCRSIn);
247
    PROJ_INTERNAL void
248
    setInterpolationCRS(const crs::CRSPtr &interpolationCRSIn);
249
    PROJ_INTERNAL void setCRSs(const CoordinateOperation *in,
250
                               bool inverseSourceTarget);
251
    PROJ_INTERNAL
252
    void setAccuracies(
253
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
254
    PROJ_INTERNAL void setHasBallparkTransformation(bool b);
255
256
    PROJ_INTERNAL void setRequiresPerCoordinateInputTime(bool b);
257
258
    PROJ_INTERNAL void
259
    setSourceCoordinateEpoch(const util::optional<common::DataEpoch> &epoch);
260
    PROJ_INTERNAL void
261
    setTargetCoordinateEpoch(const util::optional<common::DataEpoch> &epoch);
262
263
    PROJ_INTERNAL void
264
    setProperties(const util::PropertyMap
265
                      &properties); // throw(InvalidValueTypeException)
266
267
    PROJ_INTERNAL virtual CoordinateOperationNNPtr _shallowClone() const = 0;
268
269
  private:
270
    PROJ_OPAQUE_PRIVATE_DATA
271
    CoordinateOperation &operator=(const CoordinateOperation &other) = delete;
272
};
273
274
// ---------------------------------------------------------------------------
275
276
/** \brief Abstract class modelling a parameter value (OperationParameter)
277
 * or group of parameters.
278
 *
279
 * \remark Implements GeneralOperationParameter from \ref ISO_19111_2019
280
 */
281
class PROJ_GCC_DLL GeneralOperationParameter : public common::IdentifiedObject {
282
  public:
283
    //! @cond Doxygen_Suppress
284
    PROJ_DLL ~GeneralOperationParameter() override;
285
    //! @endcond
286
287
    //! @cond Doxygen_Suppress
288
    PROJ_INTERNAL bool _isEquivalentTo(
289
        const util::IComparable *other,
290
        util::IComparable::Criterion criterion =
291
            util::IComparable::Criterion::STRICT,
292
        const io::DatabaseContextPtr &dbContext = nullptr) const override = 0;
293
    //! @endcond
294
295
  protected:
296
    PROJ_INTERNAL GeneralOperationParameter();
297
    PROJ_INTERNAL
298
    GeneralOperationParameter(const GeneralOperationParameter &other);
299
300
  private:
301
    PROJ_OPAQUE_PRIVATE_DATA
302
    GeneralOperationParameter &
303
    operator=(const GeneralOperationParameter &other) = delete;
304
};
305
306
/** Shared pointer of GeneralOperationParameter */
307
using GeneralOperationParameterPtr = std::shared_ptr<GeneralOperationParameter>;
308
/** Non-null shared pointer of GeneralOperationParameter */
309
using GeneralOperationParameterNNPtr = util::nn<GeneralOperationParameterPtr>;
310
311
// ---------------------------------------------------------------------------
312
313
class OperationParameter;
314
/** Shared pointer of OperationParameter */
315
using OperationParameterPtr = std::shared_ptr<OperationParameter>;
316
/** Non-null shared pointer of OperationParameter */
317
using OperationParameterNNPtr = util::nn<OperationParameterPtr>;
318
319
/** \brief The definition of a parameter used by a coordinate operation method.
320
 *
321
 * Most parameter values are numeric, but other types of parameter values are
322
 * possible.
323
 *
324
 * \remark Implements OperationParameter from \ref ISO_19111_2019
325
 */
326
class PROJ_GCC_DLL OperationParameter final : public GeneralOperationParameter {
327
  public:
328
    //! @cond Doxygen_Suppress
329
    PROJ_DLL ~OperationParameter() override;
330
    //! @endcond
331
332
    //! @cond Doxygen_Suppress
333
    PROJ_INTERNAL bool _isEquivalentTo(
334
        const util::IComparable *other,
335
        util::IComparable::Criterion criterion =
336
            util::IComparable::Criterion::STRICT,
337
        const io::DatabaseContextPtr &dbContext = nullptr) const override;
338
    //! @endcond
339
340
    // non-standard
341
    PROJ_DLL static OperationParameterNNPtr
342
    create(const util::PropertyMap &properties);
343
344
    PROJ_DLL int getEPSGCode() PROJ_PURE_DECL;
345
346
    PROJ_DLL static const char *getNameForEPSGCode(int epsg_code) noexcept;
347
348
  protected:
349
    PROJ_INTERNAL OperationParameter();
350
    PROJ_INTERNAL OperationParameter(const OperationParameter &other);
351
    INLINED_MAKE_SHARED
352
353
  private:
354
    PROJ_OPAQUE_PRIVATE_DATA
355
    OperationParameter &operator=(const OperationParameter &other) = delete;
356
357
    // cppcheck-suppress functionStatic
358
    PROJ_INTERNAL void _exportToWKT(io::WKTFormatter *formatter)
359
        const override; // throw(io::FormattingException)
360
};
361
362
// ---------------------------------------------------------------------------
363
364
//! @cond Doxygen_Suppress
365
struct MethodMapping;
366
//! @endcond
367
368
/** \brief Abstract class modelling a parameter value (OperationParameterValue)
369
 * or group of parameter values.
370
 *
371
 * \remark Implements GeneralParameterValue from \ref ISO_19111_2019
372
 */
373
class PROJ_GCC_DLL GeneralParameterValue : public util::BaseObject,
374
                                           public io::IWKTExportable,
375
                                           public io::IJSONExportable,
376
                                           public util::IComparable {
377
  public:
378
    //! @cond Doxygen_Suppress
379
    PROJ_DLL ~GeneralParameterValue() override;
380
381
    PROJ_INTERNAL void _exportToWKT(io::WKTFormatter *formatter)
382
        const override = 0; // throw(io::FormattingException)
383
384
    PROJ_INTERNAL void _exportToJSON(io::JSONFormatter *formatter)
385
        const override = 0; // throw(FormattingException)
386
387
    PROJ_INTERNAL bool _isEquivalentTo(
388
        const util::IComparable *other,
389
        util::IComparable::Criterion criterion =
390
            util::IComparable::Criterion::STRICT,
391
        const io::DatabaseContextPtr &dbContext = nullptr) const override = 0;
392
    //! @endcond
393
394
  protected:
395
    //! @cond Doxygen_Suppress
396
    PROJ_INTERNAL GeneralParameterValue();
397
    PROJ_INTERNAL GeneralParameterValue(const GeneralParameterValue &other);
398
399
    friend class Conversion;
400
    friend class SingleOperation;
401
    friend class PointMotionOperation;
402
    PROJ_INTERNAL virtual void _exportToWKT(io::WKTFormatter *formatter,
403
                                            const MethodMapping *mapping)
404
        const = 0; // throw(io::FormattingException)
405
                   //! @endcond
406
407
  private:
408
    PROJ_OPAQUE_PRIVATE_DATA
409
    GeneralParameterValue &
410
    operator=(const GeneralParameterValue &other) = delete;
411
};
412
413
/** Shared pointer of GeneralParameterValue */
414
using GeneralParameterValuePtr = std::shared_ptr<GeneralParameterValue>;
415
/** Non-null shared pointer of GeneralParameterValue */
416
using GeneralParameterValueNNPtr = util::nn<GeneralParameterValuePtr>;
417
418
// ---------------------------------------------------------------------------
419
420
class ParameterValue;
421
/** Shared pointer of ParameterValue */
422
using ParameterValuePtr = std::shared_ptr<ParameterValue>;
423
/** Non-null shared pointer of ParameterValue */
424
using ParameterValueNNPtr = util::nn<ParameterValuePtr>;
425
426
/** \brief The value of the coordinate operation parameter.
427
 *
428
 * Most parameter values are numeric, but other types of parameter values are
429
 * possible.
430
 *
431
 * \remark Implements ParameterValue from \ref ISO_19111_2019
432
 */
433
class PROJ_GCC_DLL ParameterValue final : public util::BaseObject,
434
                                          public io::IWKTExportable,
435
                                          public util::IComparable {
436
  public:
437
    /** Type of the value. */
438
    enum class Type {
439
        /** Measure (i.e. value with a unit) */
440
        MEASURE,
441
        /** String */
442
        STRING,
443
        /** Integer */
444
        INTEGER,
445
        /** Boolean */
446
        BOOLEAN,
447
        /** Filename */
448
        FILENAME
449
    };
450
    //! @cond Doxygen_Suppress
451
    PROJ_DLL ~ParameterValue() override;
452
453
    PROJ_INTERNAL void _exportToWKT(io::WKTFormatter *formatter)
454
        const override; // throw(io::FormattingException)
455
    //! @endcond
456
457
    PROJ_DLL static ParameterValueNNPtr
458
    create(const common::Measure &measureIn);
459
    PROJ_DLL static ParameterValueNNPtr create(const char *stringValueIn);
460
    PROJ_DLL static ParameterValueNNPtr
461
    create(const std::string &stringValueIn);
462
    PROJ_DLL static ParameterValueNNPtr create(int integerValueIn);
463
    PROJ_DLL static ParameterValueNNPtr create(bool booleanValueIn);
464
    PROJ_DLL static ParameterValueNNPtr
465
    createFilename(const std::string &stringValueIn);
466
467
    PROJ_DLL const Type &type() PROJ_PURE_DECL;
468
    PROJ_DLL const common::Measure &value() PROJ_PURE_DECL;
469
    PROJ_DLL const std::string &stringValue() PROJ_PURE_DECL;
470
    PROJ_DLL const std::string &valueFile() PROJ_PURE_DECL;
471
    PROJ_DLL int integerValue() PROJ_PURE_DECL;
472
    PROJ_DLL bool booleanValue() PROJ_PURE_DECL;
473
474
    //! @cond Doxygen_Suppress
475
    PROJ_INTERNAL bool _isEquivalentTo(
476
        const util::IComparable *other,
477
        util::IComparable::Criterion criterion =
478
            util::IComparable::Criterion::STRICT,
479
        const io::DatabaseContextPtr &dbContext = nullptr) const override;
480
    //! @endcond
481
482
  protected:
483
    PROJ_INTERNAL explicit ParameterValue(const common::Measure &measureIn);
484
    PROJ_INTERNAL explicit ParameterValue(const std::string &stringValueIn,
485
                                          Type typeIn);
486
    PROJ_INTERNAL explicit ParameterValue(int integerValueIn);
487
    PROJ_INTERNAL explicit ParameterValue(bool booleanValueIn);
488
    INLINED_MAKE_SHARED
489
  private:
490
    PROJ_OPAQUE_PRIVATE_DATA
491
    ParameterValue &operator=(const ParameterValue &other) = delete;
492
};
493
494
// ---------------------------------------------------------------------------
495
496
class OperationParameterValue;
497
/** Shared pointer of OperationParameterValue */
498
using OperationParameterValuePtr = std::shared_ptr<OperationParameterValue>;
499
/** Non-null shared pointer of OperationParameterValue */
500
using OperationParameterValueNNPtr = util::nn<OperationParameterValuePtr>;
501
502
/** \brief A parameter value, ordered sequence of values, or reference to a
503
 * file of parameter values.
504
 *
505
 * This combines a OperationParameter with the corresponding ParameterValue.
506
 *
507
 * \remark Implements OperationParameterValue from \ref ISO_19111_2019
508
 */
509
class PROJ_GCC_DLL OperationParameterValue final
510
    : public GeneralParameterValue {
511
  public:
512
    //! @cond Doxygen_Suppress
513
    PROJ_DLL ~OperationParameterValue() override;
514
    //! @endcond
515
516
    PROJ_DLL const OperationParameterNNPtr &parameter() PROJ_PURE_DECL;
517
    PROJ_DLL const ParameterValueNNPtr &parameterValue() PROJ_PURE_DECL;
518
519
    PROJ_DLL static OperationParameterValueNNPtr
520
    create(const OperationParameterNNPtr &parameterIn,
521
           const ParameterValueNNPtr &valueIn);
522
523
    PROJ_PRIVATE :
524
        //! @cond Doxygen_Suppress
525
        PROJ_INTERNAL static bool
526
        convertFromAbridged(const std::string &paramName, double &val,
527
                            const common::UnitOfMeasure *&unit,
528
                            int &paramEPSGCode);
529
530
    PROJ_INTERNAL void _exportToWKT(io::WKTFormatter *formatter)
531
        const override; // throw(io::FormattingException)
532
533
    PROJ_INTERNAL void _exportToJSON(io::JSONFormatter *formatter)
534
        const override; // throw(FormattingException)
535
536
    PROJ_INTERNAL bool _isEquivalentTo(
537
        const util::IComparable *other,
538
        util::IComparable::Criterion criterion =
539
            util::IComparable::Criterion::STRICT,
540
        const io::DatabaseContextPtr &dbContext = nullptr) const override;
541
    //! @endcond
542
543
  protected:
544
    PROJ_INTERNAL
545
    OperationParameterValue(const OperationParameterNNPtr &parameterIn,
546
                            const ParameterValueNNPtr &valueIn);
547
    PROJ_INTERNAL OperationParameterValue(const OperationParameterValue &other);
548
    INLINED_MAKE_SHARED
549
550
    PROJ_INTERNAL void _exportToWKT(io::WKTFormatter *formatter,
551
                                    const MethodMapping *mapping)
552
        const override; // throw(io::FormattingException)
553
554
  private:
555
    PROJ_OPAQUE_PRIVATE_DATA
556
    OperationParameterValue &
557
    operator=(const OperationParameterValue &other) = delete;
558
};
559
560
// ---------------------------------------------------------------------------
561
562
class OperationMethod;
563
/** Shared pointer of OperationMethod */
564
using OperationMethodPtr = std::shared_ptr<OperationMethod>;
565
/** Non-null shared pointer of OperationMethod */
566
using OperationMethodNNPtr = util::nn<OperationMethodPtr>;
567
568
/** \brief The method (algorithm or procedure) used to perform the
569
 * coordinate operation.
570
 *
571
 * For a projection method, this contains the name of the projection method
572
 * and the name of the projection parameters.
573
 *
574
 * \remark Implements OperationMethod from \ref ISO_19111_2019
575
 */
576
class PROJ_GCC_DLL OperationMethod : public common::IdentifiedObject,
577
                                     public io::IJSONExportable {
578
  public:
579
    //! @cond Doxygen_Suppress
580
    PROJ_DLL ~OperationMethod() override;
581
    //! @endcond
582
583
    PROJ_DLL const util::optional<std::string> &formula() PROJ_PURE_DECL;
584
    PROJ_DLL const util::optional<metadata::Citation> &
585
    formulaCitation() PROJ_PURE_DECL;
586
    PROJ_DLL const std::vector<GeneralOperationParameterNNPtr> &
587
    parameters() PROJ_PURE_DECL;
588
589
    PROJ_DLL static OperationMethodNNPtr
590
    create(const util::PropertyMap &properties,
591
           const std::vector<GeneralOperationParameterNNPtr> &parameters);
592
593
    PROJ_DLL static OperationMethodNNPtr
594
    create(const util::PropertyMap &properties,
595
           const std::vector<OperationParameterNNPtr> &parameters);
596
597
    PROJ_DLL int getEPSGCode() PROJ_PURE_DECL;
598
599
    //! @cond Doxygen_Suppress
600
    PROJ_INTERNAL void _exportToWKT(io::WKTFormatter *formatter)
601
        const override; // throw(io::FormattingException)
602
603
    PROJ_INTERNAL void _exportToJSON(io::JSONFormatter *formatter)
604
        const override; // throw(FormattingException)
605
606
    PROJ_INTERNAL bool _isEquivalentTo(
607
        const util::IComparable *other,
608
        util::IComparable::Criterion criterion =
609
            util::IComparable::Criterion::STRICT,
610
        const io::DatabaseContextPtr &dbContext = nullptr) const override;
611
    //! @endcond
612
613
  protected:
614
    PROJ_INTERNAL OperationMethod();
615
    PROJ_INTERNAL OperationMethod(const OperationMethod &other);
616
    INLINED_MAKE_SHARED
617
    friend class Conversion;
618
619
  private:
620
    PROJ_OPAQUE_PRIVATE_DATA
621
    OperationMethod &operator=(const OperationMethod &other) = delete;
622
};
623
624
// ---------------------------------------------------------------------------
625
626
/** \brief Exception that can be thrown when an invalid operation is attempted
627
 * to be constructed.
628
 */
629
class PROJ_GCC_DLL InvalidOperation : public util::Exception {
630
  public:
631
    //! @cond Doxygen_Suppress
632
    PROJ_INTERNAL explicit InvalidOperation(const char *message);
633
    PROJ_INTERNAL explicit InvalidOperation(const std::string &message);
634
    PROJ_DLL InvalidOperation(const InvalidOperation &other);
635
    PROJ_DLL ~InvalidOperation() override;
636
    //! @endcond
637
};
638
639
// ---------------------------------------------------------------------------
640
641
class SingleOperation;
642
/** Shared pointer of SingleOperation */
643
using SingleOperationPtr = std::shared_ptr<SingleOperation>;
644
/** Non-null shared pointer of SingleOperation */
645
using SingleOperationNNPtr = util::nn<SingleOperationPtr>;
646
647
/** \brief A single (not concatenated) coordinate operation
648
 * (CoordinateOperation)
649
 *
650
 * \remark Implements SingleOperation from \ref ISO_19111_2019
651
 */
652
class PROJ_GCC_DLL SingleOperation : virtual public CoordinateOperation {
653
  public:
654
    //! @cond Doxygen_Suppress
655
    PROJ_DLL ~SingleOperation() override;
656
    //! @endcond
657
658
    PROJ_DLL const std::vector<GeneralParameterValueNNPtr> &
659
    parameterValues() PROJ_PURE_DECL;
660
    PROJ_DLL const OperationMethodNNPtr &method() PROJ_PURE_DECL;
661
662
    PROJ_DLL const ParameterValuePtr &
663
    parameterValue(const std::string &paramName,
664
                   int epsg_code = 0) const noexcept;
665
666
    PROJ_DLL const ParameterValuePtr &
667
    parameterValue(int epsg_code) const noexcept;
668
669
    PROJ_DLL const common::Measure &
670
    parameterValueMeasure(const std::string &paramName,
671
                          int epsg_code = 0) const noexcept;
672
673
    PROJ_DLL const common::Measure &
674
    parameterValueMeasure(int epsg_code) const noexcept;
675
676
    PROJ_DLL static SingleOperationNNPtr createPROJBased(
677
        const util::PropertyMap &properties, const std::string &PROJString,
678
        const crs::CRSPtr &sourceCRS, const crs::CRSPtr &targetCRS,
679
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies =
680
            std::vector<metadata::PositionalAccuracyNNPtr>());
681
682
    PROJ_DLL std::set<GridDescription>
683
    gridsNeeded(const io::DatabaseContextPtr &databaseContext,
684
                bool considerKnownGridsAsAvailable) const override;
685
686
    PROJ_DLL std::list<std::string> validateParameters() const;
687
688
    PROJ_DLL TransformationNNPtr substitutePROJAlternativeGridNames(
689
        io::DatabaseContextNNPtr databaseContext) const;
690
691
    PROJ_PRIVATE :
692
        //! @cond Doxygen_Suppress
693
694
        PROJ_DLL double
695
        parameterValueNumeric(
696
            int epsg_code,
697
            const common::UnitOfMeasure &targetUnit) const noexcept;
698
699
    PROJ_INTERNAL double parameterValueNumeric(
700
        const char *param_name,
701
        const common::UnitOfMeasure &targetUnit) const noexcept;
702
703
    PROJ_INTERNAL double
704
    parameterValueNumericAsSI(int epsg_code) const noexcept;
705
706
    PROJ_INTERNAL bool _isEquivalentTo(
707
        const util::IComparable *other,
708
        util::IComparable::Criterion criterion =
709
            util::IComparable::Criterion::STRICT,
710
        const io::DatabaseContextPtr &dbContext = nullptr) const override;
711
712
    PROJ_INTERNAL bool isLongitudeRotation() const;
713
714
    //! @endcond
715
716
  protected:
717
    PROJ_INTERNAL explicit SingleOperation(
718
        const OperationMethodNNPtr &methodIn);
719
    PROJ_INTERNAL SingleOperation(const SingleOperation &other);
720
721
    PROJ_INTERNAL void
722
    setParameterValues(const std::vector<GeneralParameterValueNNPtr> &values);
723
724
    PROJ_INTERNAL void
725
    exportTransformationToWKT(io::WKTFormatter *formatter) const;
726
727
    PROJ_INTERNAL bool
728
    exportToPROJStringGeneric(io::PROJStringFormatter *formatter) const;
729
730
    PROJ_INTERNAL bool _isEquivalentTo(const util::IComparable *other,
731
                                       util::IComparable::Criterion criterion,
732
                                       const io::DatabaseContextPtr &dbContext,
733
                                       bool inOtherDirection) const;
734
735
    PROJ_INTERNAL static GeneralParameterValueNNPtr
736
    createOperationParameterValueFromInterpolationCRS(int methodEPSGCode,
737
                                                      int crsEPSGCode);
738
739
    PROJ_INTERNAL static void
740
    exportToPROJStringChangeVerticalUnit(io::PROJStringFormatter *formatter,
741
                                         double convFactor);
742
743
  private:
744
    PROJ_OPAQUE_PRIVATE_DATA
745
    SingleOperation &operator=(const SingleOperation &other) = delete;
746
};
747
748
// ---------------------------------------------------------------------------
749
750
class Conversion;
751
/** Shared pointer of Conversion */
752
using ConversionPtr = std::shared_ptr<Conversion>;
753
/** Non-null shared pointer of Conversion */
754
using ConversionNNPtr = util::nn<ConversionPtr>;
755
756
/** \brief A mathematical operation on coordinates in which the parameter
757
 * values are defined rather than empirically derived.
758
 *
759
 * Application of the coordinate conversion introduces no error into output
760
 * coordinates. The best-known example of a coordinate conversion is a map
761
 * projection. For coordinate conversions the output coordinates are referenced
762
 * to the same datum as are the input coordinates.
763
 *
764
 * Coordinate conversions forming a component of a derived CRS have a source
765
 * crs::CRS and a target crs::CRS that are NOT specified through the source and
766
 * target
767
 * associations, but through associations from crs::DerivedCRS to
768
 * crs::SingleCRS.
769
 *
770
 * \remark Implements Conversion from \ref ISO_19111_2019
771
 */
772
773
/*!
774
775
\section projection_parameters Projection parameters
776
777
\subsection colatitude_cone_axis Co-latitude of cone axis
778
779
The rotation applied to spherical coordinates for the oblique projection,
780
measured on the conformal sphere in the plane of the meridian of origin.
781
782
EPSG:1036
783
784
\subsection center_latitude Latitude of natural origin/Center Latitude
785
786
The latitude of the point from which the values of both the geographical
787
coordinates on the ellipsoid and the grid coordinates on the projection are
788
deemed to increment or decrement for computational purposes. Alternatively it
789
may be considered as the latitude of the point which in the absence of
790
application of false coordinates has grid coordinates of (0,0).
791
792
EPSG:8801
793
794
\subsection center_longitude Longitude of natural origin/Central Meridian
795
796
The longitude of the point from which the values of both the geographical
797
coordinates on the ellipsoid and the grid coordinates on the projection are
798
deemed to increment or decrement for computational purposes. Alternatively it
799
may be considered as the longitude of the point which in the absence of
800
application of false coordinates has grid coordinates of (0,0).  Sometimes known
801
as "central meridian (CM)".
802
803
EPSG:8802
804
805
\subsection scale Scale Factor
806
807
The factor by which the map grid is reduced or enlarged during the projection
808
process, defined by its value at the natural origin.
809
810
EPSG:8805
811
812
\subsection false_easting False Easting
813
814
Since the natural origin may be at or near the centre of the projection and
815
under normal coordinate circumstances would thus give rise to negative
816
coordinates over parts of the mapped area, this origin is usually given false
817
coordinates which are large enough to avoid this inconvenience. The False
818
Easting, FE, is the value assigned to the abscissa (east or west) axis of the
819
projection grid at the natural origin.
820
821
EPSG:8806
822
823
\subsection false_northing False Northing
824
825
Since the natural origin may be at or near the centre of the projection and
826
under normal coordinate circumstances would thus give rise to negative
827
coordinates over parts of the mapped area, this origin is usually given false
828
coordinates which are large enough to avoid this inconvenience. The False
829
Northing, FN, is the value assigned to the ordinate (north or south) axis of the
830
projection grid at the natural origin.
831
832
EPSG:8807
833
834
\subsection latitude_projection_centre Latitude of projection centre
835
836
For an oblique projection, this is the latitude of the point at which the
837
azimuth of the central line is defined.
838
839
EPSG:8811
840
841
\subsection longitude_projection_centre Longitude of projection centre
842
843
For an oblique projection, this is the longitude of the point at which the
844
azimuth of the central line is defined.
845
846
EPSG:8812
847
848
\subsection azimuth_initial_line Azimuth of initial line
849
850
The azimuthal direction (north zero, east of north being positive) of the great
851
circle which is the centre line of an oblique projection. The azimuth is given
852
at the projection centre.
853
854
EPSG:8813
855
856
\subsection angle_from_recitfied_to_skrew_grid Angle from Rectified to Skew Grid
857
858
The angle at the natural origin of an oblique projection through which the
859
natural coordinate reference system is rotated to make the projection north
860
axis parallel with true north.
861
862
EPSG:8814
863
864
\subsection scale_factor_initial_line Scale factor on initial line
865
866
The factor by which the map grid is reduced or enlarged during the projection
867
process, defined by its value at the projection center.
868
869
EPSG:8815
870
871
\subsection easting_projection_centre Easting at projection centre
872
873
The easting value assigned to the projection centre.
874
875
EPSG:8816
876
877
\subsection northing_projection_centre Northing at projection centre
878
879
The northing value assigned to the projection centre.
880
881
EPSG:8817
882
883
\subsection latitude_pseudo_standard_parallel Latitude of pseudo standard
884
parallel
885
886
Latitude of the parallel on which the conic or cylindrical projection is based.
887
This latitude is not geographic, but is defined on the conformal sphere AFTER
888
its rotation to obtain the oblique aspect of the projection.
889
890
EPSG:8818
891
892
\subsection scale_factor_pseudo_standard_parallel Scale factor on pseudo
893
standard parallel
894
895
The factor by which the map grid is reduced or enlarged during the projection
896
process, defined by its value at the pseudo-standard parallel.
897
EPSG:8819
898
899
\subsection latitude_false_origin Latitude of false origin
900
901
The latitude of the point which is not the natural origin and at which grid
902
coordinate values false easting and false northing are defined.
903
904
EPSG:8821
905
906
\subsection longitude_false_origin Longitude of false origin
907
908
The longitude of the point which is not the natural origin and at which grid
909
coordinate values false easting and false northing are defined.
910
911
EPSG:8822
912
913
\subsection latitude_first_std_parallel Latitude of 1st standard parallel
914
915
For a conic projection with two standard parallels, this is the latitude of one
916
of the parallels of intersection of the cone with the ellipsoid. It is normally
917
but not necessarily that nearest to the pole. Scale is true along this parallel.
918
919
EPSG:8823
920
921
\subsection latitude_second_std_parallel Latitude of 2nd standard parallel
922
923
For a conic projection with two standard parallels, this is the latitude of one
924
of the parallels at which the cone intersects with the ellipsoid. It is normally
925
but not necessarily that nearest to the equator. Scale is true along this
926
parallel.
927
928
EPSG:8824
929
930
\subsection easting_false_origin Easting of false origin
931
932
The easting value assigned to the false origin.
933
934
EPSG:8826
935
936
\subsection northing_false_origin Northing of false origin
937
938
The northing value assigned to the false origin.
939
940
EPSG:8827
941
942
\subsection latitude_std_parallel Latitude of standard parallel
943
944
For polar aspect azimuthal projections, the parallel on which the scale factor
945
is defined to be unity.
946
947
EPSG:8832
948
949
\subsection longitude_of_origin Longitude of origin
950
951
For polar aspect azimuthal projections, the meridian along which the
952
northing axis increments and also across which parallels of latitude
953
increment towards the north pole.
954
955
EPSG:8833
956
957
*/
958
959
class PROJ_GCC_DLL Conversion : public SingleOperation {
960
  public:
961
    //! @cond Doxygen_Suppress
962
    PROJ_DLL ~Conversion() override;
963
    //! @endcond
964
965
    PROJ_DLL CoordinateOperationNNPtr inverse() const override;
966
967
    //! @cond Doxygen_Suppress
968
    PROJ_INTERNAL void _exportToWKT(io::WKTFormatter *formatter)
969
        const override; // throw(io::FormattingException)
970
    //! @endcond
971
972
    PROJ_DLL bool isUTM(int &zone, bool &north) const;
973
974
    PROJ_DLL ConversionNNPtr identify() const;
975
976
    PROJ_DLL static ConversionNNPtr
977
    create(const util::PropertyMap &properties,
978
           const OperationMethodNNPtr &methodIn,
979
           const std::vector<GeneralParameterValueNNPtr>
980
               &values); // throw InvalidOperation
981
982
    PROJ_DLL static ConversionNNPtr
983
    create(const util::PropertyMap &propertiesConversion,
984
           const util::PropertyMap &propertiesOperationMethod,
985
           const std::vector<OperationParameterNNPtr> &parameters,
986
           const std::vector<ParameterValueNNPtr>
987
               &values); // throw InvalidOperation
988
989
    PROJ_DLL static ConversionNNPtr
990
    createUTM(const util::PropertyMap &properties, int zone, bool north);
991
992
    PROJ_DLL static ConversionNNPtr createTransverseMercator(
993
        const util::PropertyMap &properties, const common::Angle &centerLat,
994
        const common::Angle &centerLong, const common::Scale &scale,
995
        const common::Length &falseEasting,
996
        const common::Length &falseNorthing);
997
998
    PROJ_DLL static ConversionNNPtr createGaussSchreiberTransverseMercator(
999
        const util::PropertyMap &properties, const common::Angle &centerLat,
1000
        const common::Angle &centerLong, const common::Scale &scale,
1001
        const common::Length &falseEasting,
1002
        const common::Length &falseNorthing);
1003
1004
    PROJ_DLL static ConversionNNPtr createTransverseMercatorSouthOriented(
1005
        const util::PropertyMap &properties, const common::Angle &centerLat,
1006
        const common::Angle &centerLong, const common::Scale &scale,
1007
        const common::Length &falseEasting,
1008
        const common::Length &falseNorthing);
1009
1010
    PROJ_DLL static ConversionNNPtr
1011
    createTwoPointEquidistant(const util::PropertyMap &properties,
1012
                              const common::Angle &latitudeFirstPoint,
1013
                              const common::Angle &longitudeFirstPoint,
1014
                              const common::Angle &latitudeSecondPoint,
1015
                              const common::Angle &longitudeSeconPoint,
1016
                              const common::Length &falseEasting,
1017
                              const common::Length &falseNorthing);
1018
1019
    PROJ_DLL static ConversionNNPtr createTunisiaMappingGrid(
1020
        const util::PropertyMap &properties, const common::Angle &centerLat,
1021
        const common::Angle &centerLong, const common::Length &falseEasting,
1022
        const common::Length &falseNorthing);
1023
1024
    PROJ_DLL static ConversionNNPtr createTunisiaMiningGrid(
1025
        const util::PropertyMap &properties, const common::Angle &centerLat,
1026
        const common::Angle &centerLong, const common::Length &falseEasting,
1027
        const common::Length &falseNorthing);
1028
1029
    PROJ_DLL static ConversionNNPtr
1030
    createAlbersEqualArea(const util::PropertyMap &properties,
1031
                          const common::Angle &latitudeFalseOrigin,
1032
                          const common::Angle &longitudeFalseOrigin,
1033
                          const common::Angle &latitudeFirstParallel,
1034
                          const common::Angle &latitudeSecondParallel,
1035
                          const common::Length &eastingFalseOrigin,
1036
                          const common::Length &northingFalseOrigin);
1037
1038
    PROJ_DLL static ConversionNNPtr createLambertConicConformal_1SP(
1039
        const util::PropertyMap &properties, const common::Angle &centerLat,
1040
        const common::Angle &centerLong, const common::Scale &scale,
1041
        const common::Length &falseEasting,
1042
        const common::Length &falseNorthing);
1043
1044
    PROJ_DLL static ConversionNNPtr createLambertConicConformal_1SP_VariantB(
1045
        const util::PropertyMap &properties,
1046
        const common::Angle &latitudeNatOrigin, const common::Scale &scale,
1047
        const common::Angle &latitudeFalseOrigin,
1048
        const common::Angle &longitudeFalseOrigin,
1049
        const common::Length &eastingFalseOrigin,
1050
        const common::Length &northingFalseOrigin);
1051
1052
    PROJ_DLL static ConversionNNPtr
1053
    createLambertConicConformal_2SP(const util::PropertyMap &properties,
1054
                                    const common::Angle &latitudeFalseOrigin,
1055
                                    const common::Angle &longitudeFalseOrigin,
1056
                                    const common::Angle &latitudeFirstParallel,
1057
                                    const common::Angle &latitudeSecondParallel,
1058
                                    const common::Length &eastingFalseOrigin,
1059
                                    const common::Length &northingFalseOrigin);
1060
1061
    PROJ_DLL static ConversionNNPtr createLambertConicConformal_2SP_Michigan(
1062
        const util::PropertyMap &properties,
1063
        const common::Angle &latitudeFalseOrigin,
1064
        const common::Angle &longitudeFalseOrigin,
1065
        const common::Angle &latitudeFirstParallel,
1066
        const common::Angle &latitudeSecondParallel,
1067
        const common::Length &eastingFalseOrigin,
1068
        const common::Length &northingFalseOrigin,
1069
        const common::Scale &ellipsoidScalingFactor);
1070
1071
    PROJ_DLL static ConversionNNPtr createLambertConicConformal_2SP_Belgium(
1072
        const util::PropertyMap &properties,
1073
        const common::Angle &latitudeFalseOrigin,
1074
        const common::Angle &longitudeFalseOrigin,
1075
        const common::Angle &latitudeFirstParallel,
1076
        const common::Angle &latitudeSecondParallel,
1077
        const common::Length &eastingFalseOrigin,
1078
        const common::Length &northingFalseOrigin);
1079
1080
    PROJ_DLL static ConversionNNPtr
1081
    createAzimuthalEquidistant(const util::PropertyMap &properties,
1082
                               const common::Angle &latitudeNatOrigin,
1083
                               const common::Angle &longitudeNatOrigin,
1084
                               const common::Length &falseEasting,
1085
                               const common::Length &falseNorthing);
1086
1087
    PROJ_DLL static ConversionNNPtr
1088
    createGuamProjection(const util::PropertyMap &properties,
1089
                         const common::Angle &latitudeNatOrigin,
1090
                         const common::Angle &longitudeNatOrigin,
1091
                         const common::Length &falseEasting,
1092
                         const common::Length &falseNorthing);
1093
1094
    PROJ_DLL static ConversionNNPtr
1095
    createBonne(const util::PropertyMap &properties,
1096
                const common::Angle &latitudeNatOrigin,
1097
                const common::Angle &longitudeNatOrigin,
1098
                const common::Length &falseEasting,
1099
                const common::Length &falseNorthing);
1100
1101
    PROJ_DLL static ConversionNNPtr createLambertCylindricalEqualAreaSpherical(
1102
        const util::PropertyMap &properties,
1103
        const common::Angle &latitudeFirstParallel,
1104
        const common::Angle &longitudeNatOrigin,
1105
        const common::Length &falseEasting,
1106
        const common::Length &falseNorthing);
1107
1108
    PROJ_DLL static ConversionNNPtr createLambertCylindricalEqualArea(
1109
        const util::PropertyMap &properties,
1110
        const common::Angle &latitudeFirstParallel,
1111
        const common::Angle &longitudeNatOrigin,
1112
        const common::Length &falseEasting,
1113
        const common::Length &falseNorthing);
1114
1115
    PROJ_DLL static ConversionNNPtr createCassiniSoldner(
1116
        const util::PropertyMap &properties, const common::Angle &centerLat,
1117
        const common::Angle &centerLong, const common::Length &falseEasting,
1118
        const common::Length &falseNorthing);
1119
1120
    PROJ_DLL static ConversionNNPtr
1121
    createEquidistantConic(const util::PropertyMap &properties,
1122
                           const common::Angle &latitudeFalseOrigin,
1123
                           const common::Angle &longitudeFalseOrigin,
1124
                           const common::Angle &latitudeFirstParallel,
1125
                           const common::Angle &latitudeSecondParallel,
1126
                           const common::Length &eastingFalseOrigin,
1127
                           const common::Length &northingFalseOrigin);
1128
1129
    PROJ_DLL static ConversionNNPtr
1130
    createEckertI(const util::PropertyMap &properties,
1131
                  const common::Angle &centerLong,
1132
                  const common::Length &falseEasting,
1133
                  const common::Length &falseNorthing);
1134
1135
    PROJ_DLL static ConversionNNPtr
1136
    createEckertII(const util::PropertyMap &properties,
1137
                   const common::Angle &centerLong,
1138
                   const common::Length &falseEasting,
1139
                   const common::Length &falseNorthing);
1140
1141
    PROJ_DLL static ConversionNNPtr
1142
    createEckertIII(const util::PropertyMap &properties,
1143
                    const common::Angle &centerLong,
1144
                    const common::Length &falseEasting,
1145
                    const common::Length &falseNorthing);
1146
1147
    PROJ_DLL static ConversionNNPtr
1148
    createEckertIV(const util::PropertyMap &properties,
1149
                   const common::Angle &centerLong,
1150
                   const common::Length &falseEasting,
1151
                   const common::Length &falseNorthing);
1152
1153
    PROJ_DLL static ConversionNNPtr
1154
    createEckertV(const util::PropertyMap &properties,
1155
                  const common::Angle &centerLong,
1156
                  const common::Length &falseEasting,
1157
                  const common::Length &falseNorthing);
1158
1159
    PROJ_DLL static ConversionNNPtr
1160
    createEckertVI(const util::PropertyMap &properties,
1161
                   const common::Angle &centerLong,
1162
                   const common::Length &falseEasting,
1163
                   const common::Length &falseNorthing);
1164
1165
    PROJ_DLL static ConversionNNPtr
1166
    createEquidistantCylindrical(const util::PropertyMap &properties,
1167
                                 const common::Angle &latitudeFirstParallel,
1168
                                 const common::Angle &longitudeNatOrigin,
1169
                                 const common::Length &falseEasting,
1170
                                 const common::Length &falseNorthing);
1171
1172
    PROJ_DLL static ConversionNNPtr createEquidistantCylindricalSpherical(
1173
        const util::PropertyMap &properties,
1174
        const common::Angle &latitudeFirstParallel,
1175
        const common::Angle &longitudeNatOrigin,
1176
        const common::Length &falseEasting,
1177
        const common::Length &falseNorthing);
1178
1179
    PROJ_DLL static ConversionNNPtr
1180
    createGall(const util::PropertyMap &properties,
1181
               const common::Angle &centerLong,
1182
               const common::Length &falseEasting,
1183
               const common::Length &falseNorthing);
1184
1185
    PROJ_DLL static ConversionNNPtr
1186
    createGoodeHomolosine(const util::PropertyMap &properties,
1187
                          const common::Angle &centerLong,
1188
                          const common::Length &falseEasting,
1189
                          const common::Length &falseNorthing);
1190
1191
    PROJ_DLL static ConversionNNPtr
1192
    createInterruptedGoodeHomolosine(const util::PropertyMap &properties,
1193
                                     const common::Angle &centerLong,
1194
                                     const common::Length &falseEasting,
1195
                                     const common::Length &falseNorthing);
1196
1197
    PROJ_DLL static ConversionNNPtr createGeostationarySatelliteSweepX(
1198
        const util::PropertyMap &properties, const common::Angle &centerLong,
1199
        const common::Length &height, const common::Length &falseEasting,
1200
        const common::Length &falseNorthing);
1201
1202
    PROJ_DLL static ConversionNNPtr createGeostationarySatelliteSweepY(
1203
        const util::PropertyMap &properties, const common::Angle &centerLong,
1204
        const common::Length &height, const common::Length &falseEasting,
1205
        const common::Length &falseNorthing);
1206
1207
    PROJ_DLL static ConversionNNPtr createGnomonic(
1208
        const util::PropertyMap &properties, const common::Angle &centerLat,
1209
        const common::Angle &centerLong, const common::Length &falseEasting,
1210
        const common::Length &falseNorthing);
1211
1212
    PROJ_DLL static ConversionNNPtr createHotineObliqueMercatorVariantA(
1213
        const util::PropertyMap &properties,
1214
        const common::Angle &latitudeProjectionCentre,
1215
        const common::Angle &longitudeProjectionCentre,
1216
        const common::Angle &azimuthInitialLine,
1217
        const common::Angle &angleFromRectifiedToSkrewGrid,
1218
        const common::Scale &scale, const common::Length &falseEasting,
1219
        const common::Length &falseNorthing);
1220
1221
    PROJ_DLL static ConversionNNPtr createHotineObliqueMercatorVariantB(
1222
        const util::PropertyMap &properties,
1223
        const common::Angle &latitudeProjectionCentre,
1224
        const common::Angle &longitudeProjectionCentre,
1225
        const common::Angle &azimuthInitialLine,
1226
        const common::Angle &angleFromRectifiedToSkrewGrid,
1227
        const common::Scale &scale,
1228
        const common::Length &eastingProjectionCentre,
1229
        const common::Length &northingProjectionCentre);
1230
1231
    PROJ_DLL static ConversionNNPtr
1232
    createHotineObliqueMercatorTwoPointNaturalOrigin(
1233
        const util::PropertyMap &properties,
1234
        const common::Angle &latitudeProjectionCentre,
1235
        const common::Angle &latitudePoint1,
1236
        const common::Angle &longitudePoint1,
1237
        const common::Angle &latitudePoint2,
1238
        const common::Angle &longitudePoint2, const common::Scale &scale,
1239
        const common::Length &eastingProjectionCentre,
1240
        const common::Length &northingProjectionCentre);
1241
1242
    PROJ_DLL static ConversionNNPtr
1243
    createLabordeObliqueMercator(const util::PropertyMap &properties,
1244
                                 const common::Angle &latitudeProjectionCentre,
1245
                                 const common::Angle &longitudeProjectionCentre,
1246
                                 const common::Angle &azimuthInitialLine,
1247
                                 const common::Scale &scale,
1248
                                 const common::Length &falseEasting,
1249
                                 const common::Length &falseNorthing);
1250
1251
    PROJ_DLL static ConversionNNPtr createInternationalMapWorldPolyconic(
1252
        const util::PropertyMap &properties, const common::Angle &centerLong,
1253
        const common::Angle &latitudeFirstParallel,
1254
        const common::Angle &latitudeSecondParallel,
1255
        const common::Length &falseEasting,
1256
        const common::Length &falseNorthing);
1257
1258
    PROJ_DLL static ConversionNNPtr createKrovakNorthOriented(
1259
        const util::PropertyMap &properties,
1260
        const common::Angle &latitudeProjectionCentre,
1261
        const common::Angle &longitudeOfOrigin,
1262
        const common::Angle &colatitudeConeAxis,
1263
        const common::Angle &latitudePseudoStandardParallel,
1264
        const common::Scale &scaleFactorPseudoStandardParallel,
1265
        const common::Length &falseEasting,
1266
        const common::Length &falseNorthing);
1267
1268
    PROJ_DLL static ConversionNNPtr
1269
    createKrovak(const util::PropertyMap &properties,
1270
                 const common::Angle &latitudeProjectionCentre,
1271
                 const common::Angle &longitudeOfOrigin,
1272
                 const common::Angle &colatitudeConeAxis,
1273
                 const common::Angle &latitudePseudoStandardParallel,
1274
                 const common::Scale &scaleFactorPseudoStandardParallel,
1275
                 const common::Length &falseEasting,
1276
                 const common::Length &falseNorthing);
1277
1278
    PROJ_DLL static ConversionNNPtr
1279
    createLambertAzimuthalEqualArea(const util::PropertyMap &properties,
1280
                                    const common::Angle &latitudeNatOrigin,
1281
                                    const common::Angle &longitudeNatOrigin,
1282
                                    const common::Length &falseEasting,
1283
                                    const common::Length &falseNorthing);
1284
1285
    PROJ_DLL static ConversionNNPtr
1286
    createMillerCylindrical(const util::PropertyMap &properties,
1287
                            const common::Angle &centerLong,
1288
                            const common::Length &falseEasting,
1289
                            const common::Length &falseNorthing);
1290
1291
    PROJ_DLL static ConversionNNPtr createMercatorVariantA(
1292
        const util::PropertyMap &properties, const common::Angle &centerLat,
1293
        const common::Angle &centerLong, const common::Scale &scale,
1294
        const common::Length &falseEasting,
1295
        const common::Length &falseNorthing);
1296
1297
    PROJ_DLL static ConversionNNPtr
1298
    createMercatorVariantB(const util::PropertyMap &properties,
1299
                           const common::Angle &latitudeFirstParallel,
1300
                           const common::Angle &centerLong,
1301
                           const common::Length &falseEasting,
1302
                           const common::Length &falseNorthing);
1303
1304
    PROJ_DLL static ConversionNNPtr createPopularVisualisationPseudoMercator(
1305
        const util::PropertyMap &properties, const common::Angle &centerLat,
1306
        const common::Angle &centerLong, const common::Length &falseEasting,
1307
        const common::Length &falseNorthing);
1308
1309
    PROJ_DLL static ConversionNNPtr createMercatorSpherical(
1310
        const util::PropertyMap &properties, const common::Angle &centerLat,
1311
        const common::Angle &centerLong, const common::Length &falseEasting,
1312
        const common::Length &falseNorthing);
1313
1314
    PROJ_DLL static ConversionNNPtr
1315
    createMollweide(const util::PropertyMap &properties,
1316
                    const common::Angle &centerLong,
1317
                    const common::Length &falseEasting,
1318
                    const common::Length &falseNorthing);
1319
1320
    PROJ_DLL static ConversionNNPtr createNewZealandMappingGrid(
1321
        const util::PropertyMap &properties, const common::Angle &centerLat,
1322
        const common::Angle &centerLong, const common::Length &falseEasting,
1323
        const common::Length &falseNorthing);
1324
1325
    PROJ_DLL static ConversionNNPtr createObliqueStereographic(
1326
        const util::PropertyMap &properties, const common::Angle &centerLat,
1327
        const common::Angle &centerLong, const common::Scale &scale,
1328
        const common::Length &falseEasting,
1329
        const common::Length &falseNorthing);
1330
1331
    PROJ_DLL static ConversionNNPtr createOrthographic(
1332
        const util::PropertyMap &properties, const common::Angle &centerLat,
1333
        const common::Angle &centerLong, const common::Length &falseEasting,
1334
        const common::Length &falseNorthing);
1335
1336
    PROJ_DLL static ConversionNNPtr createLocalOrthographic(
1337
        const util::PropertyMap &properties, const common::Angle &centerLat,
1338
        const common::Angle &centerLong,
1339
        const common::Angle &azimuthInitialLine, const common::Scale &scale,
1340
        const common::Length &falseEasting,
1341
        const common::Length &falseNorthing);
1342
1343
    PROJ_DLL static ConversionNNPtr createAmericanPolyconic(
1344
        const util::PropertyMap &properties, const common::Angle &centerLat,
1345
        const common::Angle &centerLong, const common::Length &falseEasting,
1346
        const common::Length &falseNorthing);
1347
1348
    PROJ_DLL static ConversionNNPtr createPolarStereographicVariantA(
1349
        const util::PropertyMap &properties, const common::Angle &centerLat,
1350
        const common::Angle &centerLong, const common::Scale &scale,
1351
        const common::Length &falseEasting,
1352
        const common::Length &falseNorthing);
1353
1354
    PROJ_DLL static ConversionNNPtr createPolarStereographicVariantB(
1355
        const util::PropertyMap &properties,
1356
        const common::Angle &latitudeStandardParallel,
1357
        const common::Angle &longitudeOfOrigin,
1358
        const common::Length &falseEasting,
1359
        const common::Length &falseNorthing);
1360
1361
    PROJ_DLL static ConversionNNPtr
1362
    createRobinson(const util::PropertyMap &properties,
1363
                   const common::Angle &centerLong,
1364
                   const common::Length &falseEasting,
1365
                   const common::Length &falseNorthing);
1366
1367
    PROJ_DLL static ConversionNNPtr
1368
    createSinusoidal(const util::PropertyMap &properties,
1369
                     const common::Angle &centerLong,
1370
                     const common::Length &falseEasting,
1371
                     const common::Length &falseNorthing);
1372
1373
    PROJ_DLL static ConversionNNPtr createStereographic(
1374
        const util::PropertyMap &properties, const common::Angle &centerLat,
1375
        const common::Angle &centerLong, const common::Scale &scale,
1376
        const common::Length &falseEasting,
1377
        const common::Length &falseNorthing);
1378
1379
    PROJ_DLL static ConversionNNPtr
1380
    createVanDerGrinten(const util::PropertyMap &properties,
1381
                        const common::Angle &centerLong,
1382
                        const common::Length &falseEasting,
1383
                        const common::Length &falseNorthing);
1384
1385
    PROJ_DLL static ConversionNNPtr
1386
    createWagnerI(const util::PropertyMap &properties,
1387
                  const common::Angle &centerLong,
1388
                  const common::Length &falseEasting,
1389
                  const common::Length &falseNorthing);
1390
1391
    PROJ_DLL static ConversionNNPtr
1392
    createWagnerII(const util::PropertyMap &properties,
1393
                   const common::Angle &centerLong,
1394
                   const common::Length &falseEasting,
1395
                   const common::Length &falseNorthing);
1396
1397
    PROJ_DLL static ConversionNNPtr
1398
    createWagnerIII(const util::PropertyMap &properties,
1399
                    const common::Angle &latitudeTrueScale,
1400
                    const common::Angle &centerLong,
1401
                    const common::Length &falseEasting,
1402
                    const common::Length &falseNorthing);
1403
1404
    PROJ_DLL static ConversionNNPtr
1405
    createWagnerIV(const util::PropertyMap &properties,
1406
                   const common::Angle &centerLong,
1407
                   const common::Length &falseEasting,
1408
                   const common::Length &falseNorthing);
1409
1410
    PROJ_DLL static ConversionNNPtr
1411
    createWagnerV(const util::PropertyMap &properties,
1412
                  const common::Angle &centerLong,
1413
                  const common::Length &falseEasting,
1414
                  const common::Length &falseNorthing);
1415
1416
    PROJ_DLL static ConversionNNPtr
1417
    createWagnerVI(const util::PropertyMap &properties,
1418
                   const common::Angle &centerLong,
1419
                   const common::Length &falseEasting,
1420
                   const common::Length &falseNorthing);
1421
1422
    PROJ_DLL static ConversionNNPtr
1423
    createWagnerVII(const util::PropertyMap &properties,
1424
                    const common::Angle &centerLong,
1425
                    const common::Length &falseEasting,
1426
                    const common::Length &falseNorthing);
1427
1428
    PROJ_DLL static ConversionNNPtr createQuadrilateralizedSphericalCube(
1429
        const util::PropertyMap &properties, const common::Angle &centerLat,
1430
        const common::Angle &centerLong, const common::Length &falseEasting,
1431
        const common::Length &falseNorthing);
1432
1433
    PROJ_DLL static ConversionNNPtr createSphericalCrossTrackHeight(
1434
        const util::PropertyMap &properties, const common::Angle &pegPointLat,
1435
        const common::Angle &pegPointLong, const common::Angle &pegPointHeading,
1436
        const common::Length &pegPointHeight);
1437
1438
    PROJ_DLL static ConversionNNPtr
1439
    createEqualEarth(const util::PropertyMap &properties,
1440
                     const common::Angle &centerLong,
1441
                     const common::Length &falseEasting,
1442
                     const common::Length &falseNorthing);
1443
1444
    PROJ_DLL static ConversionNNPtr
1445
    createVerticalPerspective(const util::PropertyMap &properties,
1446
                              const common::Angle &topoOriginLat,
1447
                              const common::Angle &topoOriginLong,
1448
                              const common::Length &topoOriginHeight,
1449
                              const common::Length &viewPointHeight,
1450
                              const common::Length &falseEasting,
1451
                              const common::Length &falseNorthing);
1452
1453
    PROJ_DLL static ConversionNNPtr createPoleRotationGRIBConvention(
1454
        const util::PropertyMap &properties,
1455
        const common::Angle &southPoleLatInUnrotatedCRS,
1456
        const common::Angle &southPoleLongInUnrotatedCRS,
1457
        const common::Angle &axisRotation);
1458
1459
    PROJ_DLL static ConversionNNPtr createPoleRotationNetCDFCFConvention(
1460
        const util::PropertyMap &properties,
1461
        const common::Angle &gridNorthPoleLatitude,
1462
        const common::Angle &gridNorthPoleLongitude,
1463
        const common::Angle &northPoleGridLongitude);
1464
1465
    PROJ_DLL static ConversionNNPtr
1466
    createChangeVerticalUnit(const util::PropertyMap &properties,
1467
                             const common::Scale &factor);
1468
1469
    PROJ_DLL static ConversionNNPtr
1470
    createChangeVerticalUnit(const util::PropertyMap &properties);
1471
1472
    PROJ_DLL static ConversionNNPtr
1473
    createHeightDepthReversal(const util::PropertyMap &properties);
1474
1475
    PROJ_DLL static ConversionNNPtr createAxisOrderReversal(bool is3D);
1476
1477
    PROJ_DLL static ConversionNNPtr
1478
    createGeographicGeocentric(const util::PropertyMap &properties);
1479
1480
    PROJ_DLL static ConversionNNPtr
1481
    createGeographic2DOffsets(const util::PropertyMap &properties,
1482
                              const common::Angle &offsetLat,
1483
                              const common::Angle &offsetLong);
1484
1485
    PROJ_DLL static ConversionNNPtr createGeographic3DOffsets(
1486
        const util::PropertyMap &properties, const common::Angle &offsetLat,
1487
        const common::Angle &offsetLong, const common::Length &offsetHeight);
1488
1489
    PROJ_DLL static ConversionNNPtr createGeographic2DWithHeightOffsets(
1490
        const util::PropertyMap &properties, const common::Angle &offsetLat,
1491
        const common::Angle &offsetLong, const common::Length &offsetHeight);
1492
1493
    PROJ_DLL static ConversionNNPtr
1494
    createVerticalOffset(const util::PropertyMap &properties,
1495
                         const common::Length &offsetHeight);
1496
1497
    PROJ_DLL ConversionPtr convertToOtherMethod(int targetEPSGCode) const;
1498
1499
    PROJ_PRIVATE :
1500
        //! @cond Doxygen_Suppress
1501
        PROJ_INTERNAL void
1502
        _exportToPROJString(io::PROJStringFormatter *formatter)
1503
            const override; // throw(FormattingException)
1504
1505
    PROJ_INTERNAL void _exportToJSON(io::JSONFormatter *formatter)
1506
        const override; // throw(FormattingException)
1507
1508
    PROJ_INTERNAL const char *getESRIMethodName() const;
1509
1510
    PROJ_INTERNAL const char *getWKT1GDALMethodName() const;
1511
1512
    PROJ_INTERNAL ConversionNNPtr shallowClone() const;
1513
1514
    PROJ_INTERNAL ConversionNNPtr alterParametersLinearUnit(
1515
        const common::UnitOfMeasure &unit, bool convertToNewUnit) const;
1516
1517
    PROJ_INTERNAL static ConversionNNPtr
1518
    createGeographicGeocentric(const crs::CRSNNPtr &sourceCRS,
1519
                               const crs::CRSNNPtr &targetCRS);
1520
1521
    PROJ_INTERNAL static ConversionNNPtr
1522
    createGeographicGeocentricLatitude(const crs::CRSNNPtr &sourceCRS,
1523
                                       const crs::CRSNNPtr &targetCRS);
1524
1525
    //! @endcond
1526
1527
  protected:
1528
    PROJ_INTERNAL
1529
    Conversion(const OperationMethodNNPtr &methodIn,
1530
               const std::vector<GeneralParameterValueNNPtr> &values);
1531
    PROJ_INTERNAL Conversion(const Conversion &other);
1532
    INLINED_MAKE_SHARED
1533
1534
    PROJ_FRIEND(crs::ProjectedCRS);
1535
    PROJ_INTERNAL bool addWKTExtensionNode(io::WKTFormatter *formatter) const;
1536
1537
    PROJ_INTERNAL CoordinateOperationNNPtr _shallowClone() const override;
1538
1539
  private:
1540
    PROJ_OPAQUE_PRIVATE_DATA
1541
    Conversion &operator=(const Conversion &other) = delete;
1542
1543
    PROJ_INTERNAL static ConversionNNPtr
1544
    create(const util::PropertyMap &properties, int method_epsg_code,
1545
           const std::vector<ParameterValueNNPtr> &values);
1546
1547
    PROJ_INTERNAL static ConversionNNPtr
1548
    create(const util::PropertyMap &properties, const char *method_wkt2_name,
1549
           const std::vector<ParameterValueNNPtr> &values);
1550
};
1551
1552
// ---------------------------------------------------------------------------
1553
1554
/** \brief A mathematical operation on coordinates in which parameters are
1555
 * empirically derived from data containing the coordinates of a series of
1556
 * points in both coordinate reference systems.
1557
 *
1558
 * This computational process is usually "over-determined", allowing derivation
1559
 * of error (or accuracy) estimates for the coordinate transformation. Also,
1560
 * the stochastic nature of the parameters may result in multiple (different)
1561
 * versions of the same coordinate transformations between the same source and
1562
 * target CRSs. Any single coordinate operation in which the input and output
1563
 * coordinates are referenced to different datums (reference frames) will be a
1564
 * coordinate transformation.
1565
 *
1566
 * \remark Implements Transformation from \ref ISO_19111_2019
1567
 */
1568
class PROJ_GCC_DLL Transformation : public SingleOperation {
1569
  public:
1570
    //! @cond Doxygen_Suppress
1571
    PROJ_DLL ~Transformation() override;
1572
    //! @endcond
1573
1574
    PROJ_DLL const crs::CRSNNPtr &sourceCRS() PROJ_PURE_DECL;
1575
    PROJ_DLL const crs::CRSNNPtr &targetCRS() PROJ_PURE_DECL;
1576
1577
    PROJ_DLL CoordinateOperationNNPtr inverse() const override;
1578
1579
    PROJ_DLL static TransformationNNPtr
1580
    create(const util::PropertyMap &properties,
1581
           const crs::CRSNNPtr &sourceCRSIn, const crs::CRSNNPtr &targetCRSIn,
1582
           const crs::CRSPtr &interpolationCRSIn,
1583
           const OperationMethodNNPtr &methodIn,
1584
           const std::vector<GeneralParameterValueNNPtr> &values,
1585
           const std::vector<metadata::PositionalAccuracyNNPtr>
1586
               &accuracies); // throw InvalidOperation
1587
1588
    PROJ_DLL static TransformationNNPtr
1589
    create(const util::PropertyMap &propertiesTransformation,
1590
           const crs::CRSNNPtr &sourceCRSIn, const crs::CRSNNPtr &targetCRSIn,
1591
           const crs::CRSPtr &interpolationCRSIn,
1592
           const util::PropertyMap &propertiesOperationMethod,
1593
           const std::vector<OperationParameterNNPtr> &parameters,
1594
           const std::vector<ParameterValueNNPtr> &values,
1595
           const std::vector<metadata::PositionalAccuracyNNPtr>
1596
               &accuracies); // throw InvalidOperation
1597
1598
    PROJ_DLL static TransformationNNPtr createGeocentricTranslations(
1599
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1600
        const crs::CRSNNPtr &targetCRSIn, double translationXMetre,
1601
        double translationYMetre, double translationZMetre,
1602
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1603
1604
    PROJ_DLL static TransformationNNPtr createPositionVector(
1605
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1606
        const crs::CRSNNPtr &targetCRSIn, double translationXMetre,
1607
        double translationYMetre, double translationZMetre,
1608
        double rotationXArcSecond, double rotationYArcSecond,
1609
        double rotationZArcSecond, double scaleDifferencePPM,
1610
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1611
1612
    PROJ_DLL static TransformationNNPtr createCoordinateFrameRotation(
1613
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1614
        const crs::CRSNNPtr &targetCRSIn, double translationXMetre,
1615
        double translationYMetre, double translationZMetre,
1616
        double rotationXArcSecond, double rotationYArcSecond,
1617
        double rotationZArcSecond, double scaleDifferencePPM,
1618
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1619
1620
    PROJ_DLL static TransformationNNPtr createTimeDependentPositionVector(
1621
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1622
        const crs::CRSNNPtr &targetCRSIn, double translationXMetre,
1623
        double translationYMetre, double translationZMetre,
1624
        double rotationXArcSecond, double rotationYArcSecond,
1625
        double rotationZArcSecond, double scaleDifferencePPM,
1626
        double rateTranslationX, double rateTranslationY,
1627
        double rateTranslationZ, double rateRotationX, double rateRotationY,
1628
        double rateRotationZ, double rateScaleDifference,
1629
        double referenceEpochYear,
1630
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1631
1632
    PROJ_DLL static TransformationNNPtr
1633
    createTimeDependentCoordinateFrameRotation(
1634
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1635
        const crs::CRSNNPtr &targetCRSIn, double translationXMetre,
1636
        double translationYMetre, double translationZMetre,
1637
        double rotationXArcSecond, double rotationYArcSecond,
1638
        double rotationZArcSecond, double scaleDifferencePPM,
1639
        double rateTranslationX, double rateTranslationY,
1640
        double rateTranslationZ, double rateRotationX, double rateRotationY,
1641
        double rateRotationZ, double rateScaleDifference,
1642
        double referenceEpochYear,
1643
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1644
1645
    PROJ_DLL static TransformationNNPtr createTOWGS84(
1646
        const crs::CRSNNPtr &sourceCRSIn,
1647
        const std::vector<double> &TOWGS84Parameters); // throw InvalidOperation
1648
1649
    PROJ_DLL static TransformationNNPtr createNTv2(
1650
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1651
        const crs::CRSNNPtr &targetCRSIn, const std::string &filename,
1652
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1653
1654
    PROJ_DLL static TransformationNNPtr createMolodensky(
1655
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1656
        const crs::CRSNNPtr &targetCRSIn, double translationXMetre,
1657
        double translationYMetre, double translationZMetre,
1658
        double semiMajorAxisDifferenceMetre, double flattingDifference,
1659
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1660
1661
    PROJ_DLL static TransformationNNPtr createAbridgedMolodensky(
1662
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1663
        const crs::CRSNNPtr &targetCRSIn, double translationXMetre,
1664
        double translationYMetre, double translationZMetre,
1665
        double semiMajorAxisDifferenceMetre, double flattingDifference,
1666
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1667
1668
    PROJ_DLL static TransformationNNPtr
1669
    createGravityRelatedHeightToGeographic3D(
1670
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1671
        const crs::CRSNNPtr &targetCRSIn, const crs::CRSPtr &interpolationCRSIn,
1672
        const std::string &filename,
1673
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1674
1675
    PROJ_DLL static TransformationNNPtr createVERTCON(
1676
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1677
        const crs::CRSNNPtr &targetCRSIn, const std::string &filename,
1678
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1679
1680
    PROJ_DLL static TransformationNNPtr createLongitudeRotation(
1681
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1682
        const crs::CRSNNPtr &targetCRSIn, const common::Angle &offset);
1683
1684
    PROJ_DLL static TransformationNNPtr createGeographic2DOffsets(
1685
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1686
        const crs::CRSNNPtr &targetCRSIn, const common::Angle &offsetLat,
1687
        const common::Angle &offsetLong,
1688
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1689
1690
    PROJ_DLL static TransformationNNPtr createGeographic3DOffsets(
1691
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1692
        const crs::CRSNNPtr &targetCRSIn, const common::Angle &offsetLat,
1693
        const common::Angle &offsetLong, const common::Length &offsetHeight,
1694
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1695
1696
    PROJ_DLL static TransformationNNPtr createGeographic2DWithHeightOffsets(
1697
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1698
        const crs::CRSNNPtr &targetCRSIn, const common::Angle &offsetLat,
1699
        const common::Angle &offsetLong, const common::Length &offsetHeight,
1700
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1701
1702
    PROJ_DLL static TransformationNNPtr createCartesianGridOffsets(
1703
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1704
        const crs::CRSNNPtr &targetCRSIn, const common::Length &eastingOffset,
1705
        const common::Length &northingOffset,
1706
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1707
1708
    PROJ_DLL static TransformationNNPtr createVerticalOffset(
1709
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1710
        const crs::CRSNNPtr &targetCRSIn, const common::Length &offsetHeight,
1711
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1712
1713
    PROJ_DLL static TransformationNNPtr createChangeVerticalUnit(
1714
        const util::PropertyMap &properties, const crs::CRSNNPtr &sourceCRSIn,
1715
        const crs::CRSNNPtr &targetCRSIn, const common::Scale &factor,
1716
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1717
1718
    PROJ_PRIVATE :
1719
        //! @cond Doxygen_Suppress
1720
        PROJ_INTERNAL const std::string &
1721
        getPROJ4NadgridsCompatibleFilename() const;
1722
1723
    PROJ_FOR_TEST std::vector<double> getTOWGS84Parameters(
1724
        bool canThrowException) const; // throw(io::FormattingException)
1725
1726
    PROJ_INTERNAL const std::string &getHeightToGeographic3DFilename() const;
1727
1728
    PROJ_INTERNAL void _exportToWKT(io::WKTFormatter *formatter)
1729
        const override; // throw(io::FormattingException)
1730
1731
    PROJ_INTERNAL void _exportToJSON(io::JSONFormatter *formatter)
1732
        const override; // throw(FormattingException)
1733
1734
    PROJ_INTERNAL TransformationNNPtr shallowClone() const;
1735
1736
    PROJ_INTERNAL TransformationNNPtr
1737
    promoteTo3D(const std::string &newName,
1738
                const io::DatabaseContextPtr &dbContext) const;
1739
1740
    PROJ_INTERNAL TransformationNNPtr
1741
    demoteTo2D(const std::string &newName,
1742
               const io::DatabaseContextPtr &dbContext) const;
1743
1744
    PROJ_INTERNAL static bool
1745
    isGeographic3DToGravityRelatedHeight(const OperationMethodNNPtr &method,
1746
                                         bool allowInverse);
1747
    //! @endcond
1748
1749
  protected:
1750
    PROJ_INTERNAL Transformation(
1751
        const crs::CRSNNPtr &sourceCRSIn, const crs::CRSNNPtr &targetCRSIn,
1752
        const crs::CRSPtr &interpolationCRSIn,
1753
        const OperationMethodNNPtr &methodIn,
1754
        const std::vector<GeneralParameterValueNNPtr> &values,
1755
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1756
    PROJ_INTERNAL Transformation(const Transformation &other);
1757
    INLINED_MAKE_SHARED
1758
1759
    PROJ_INTERNAL void _exportToPROJString(io::PROJStringFormatter *formatter)
1760
        const override; // throw(FormattingException)
1761
1762
    PROJ_FRIEND(CoordinateOperation);
1763
    PROJ_FRIEND(CoordinateOperationFactory);
1764
    PROJ_FRIEND(SingleOperation);
1765
    PROJ_INTERNAL TransformationNNPtr inverseAsTransformation() const;
1766
1767
    PROJ_INTERNAL CoordinateOperationNNPtr _shallowClone() const override;
1768
1769
  private:
1770
    PROJ_OPAQUE_PRIVATE_DATA
1771
};
1772
1773
// ---------------------------------------------------------------------------
1774
1775
class PointMotionOperation;
1776
/** Shared pointer of PointMotionOperation */
1777
using PointMotionOperationPtr = std::shared_ptr<PointMotionOperation>;
1778
/** Non-null shared pointer of PointMotionOperation */
1779
using PointMotionOperationNNPtr = util::nn<PointMotionOperationPtr>;
1780
1781
/** \brief A mathematical operation that describes the change of coordinate
1782
 * values within one coordinate reference system due to the motion of the
1783
 * point between one coordinate epoch and another coordinate epoch.
1784
 *
1785
 * The motion is due to tectonic plate movement or deformation.
1786
 *
1787
 * \remark Implements PointMotionOperation from \ref ISO_19111_2019
1788
 */
1789
class PROJ_GCC_DLL PointMotionOperation : public SingleOperation {
1790
  public:
1791
    // TODO
1792
    //! @cond Doxygen_Suppress
1793
    PROJ_DLL ~PointMotionOperation() override;
1794
    //! @endcond
1795
1796
    PROJ_DLL const crs::CRSNNPtr &sourceCRS() PROJ_PURE_DECL;
1797
1798
    PROJ_DLL CoordinateOperationNNPtr inverse() const override;
1799
1800
    PROJ_DLL static PointMotionOperationNNPtr
1801
    create(const util::PropertyMap &properties, const crs::CRSNNPtr &crsIn,
1802
           const OperationMethodNNPtr &methodIn,
1803
           const std::vector<GeneralParameterValueNNPtr> &values,
1804
           const std::vector<metadata::PositionalAccuracyNNPtr>
1805
               &accuracies); // throw InvalidOperation
1806
1807
    PROJ_DLL static PointMotionOperationNNPtr
1808
    create(const util::PropertyMap &propertiesOperation,
1809
           const crs::CRSNNPtr &crsIn,
1810
           const util::PropertyMap &propertiesOperationMethod,
1811
           const std::vector<OperationParameterNNPtr> &parameters,
1812
           const std::vector<ParameterValueNNPtr> &values,
1813
           const std::vector<metadata::PositionalAccuracyNNPtr>
1814
               &accuracies); // throw InvalidOperation
1815
1816
    PROJ_DLL PointMotionOperationNNPtr substitutePROJAlternativeGridNames(
1817
        io::DatabaseContextNNPtr databaseContext) const;
1818
1819
    PROJ_PRIVATE :
1820
        //! @cond Doxygen_Suppress
1821
        PROJ_INTERNAL PointMotionOperationNNPtr
1822
        shallowClone() const;
1823
1824
    PROJ_INTERNAL PointMotionOperationNNPtr
1825
    cloneWithEpochs(const common::DataEpoch &sourceEpoch,
1826
                    const common::DataEpoch &targetEpoch) const;
1827
1828
    PROJ_INTERNAL void _exportToPROJString(io::PROJStringFormatter *formatter)
1829
        const override; // throw(FormattingException)
1830
1831
    PROJ_INTERNAL void _exportToWKT(io::WKTFormatter *formatter)
1832
        const override; // throw(io::FormattingException)
1833
1834
    PROJ_INTERNAL void _exportToJSON(io::JSONFormatter *formatter)
1835
        const override; // throw(FormattingException)
1836
1837
    //! @endcond
1838
1839
  protected:
1840
    PROJ_INTERNAL PointMotionOperation(
1841
        const crs::CRSNNPtr &crsIn, const OperationMethodNNPtr &methodIn,
1842
        const std::vector<GeneralParameterValueNNPtr> &values,
1843
        const std::vector<metadata::PositionalAccuracyNNPtr> &accuracies);
1844
    PROJ_INTERNAL PointMotionOperation(const PointMotionOperation &other);
1845
    INLINED_MAKE_SHARED
1846
1847
    PROJ_INTERNAL CoordinateOperationNNPtr _shallowClone() const override;
1848
1849
  private:
1850
    PointMotionOperation &operator=(const PointMotionOperation &) = delete;
1851
};
1852
1853
// ---------------------------------------------------------------------------
1854
1855
class ConcatenatedOperation;
1856
/** Shared pointer of ConcatenatedOperation */
1857
using ConcatenatedOperationPtr = std::shared_ptr<ConcatenatedOperation>;
1858
/** Non-null shared pointer of ConcatenatedOperation */
1859
using ConcatenatedOperationNNPtr = util::nn<ConcatenatedOperationPtr>;
1860
1861
/** \brief An ordered sequence of two or more single coordinate operations
1862
 * (SingleOperation).
1863
 *
1864
 * The sequence of coordinate operations is constrained by the requirement
1865
 * that
1866
 * the source coordinate reference system of step n+1 shall be the same as
1867
 * the target coordinate reference system of step n.
1868
 *
1869
 * \remark Implements ConcatenatedOperation from \ref ISO_19111_2019
1870
 */
1871
class PROJ_GCC_DLL ConcatenatedOperation final : public CoordinateOperation {
1872
  public:
1873
    //! @cond Doxygen_Suppress
1874
    PROJ_DLL ~ConcatenatedOperation() override;
1875
    //! @endcond
1876
1877
    PROJ_DLL const std::vector<CoordinateOperationNNPtr> &operations() const;
1878
1879
    PROJ_DLL CoordinateOperationNNPtr inverse() const override;
1880
1881
    PROJ_DLL static ConcatenatedOperationNNPtr
1882
    create(const util::PropertyMap &properties,
1883
           const std::vector<CoordinateOperationNNPtr> &operationsIn,
1884
           const std::vector<metadata::PositionalAccuracyNNPtr>
1885
               &accuracies); // throw InvalidOperation
1886
1887
    PROJ_DLL static CoordinateOperationNNPtr createComputeMetadata(
1888
        const std::vector<CoordinateOperationNNPtr> &operationsIn,
1889
        bool checkExtent); // throw InvalidOperation
1890
1891
    PROJ_DLL std::set<GridDescription>
1892
    gridsNeeded(const io::DatabaseContextPtr &databaseContext,
1893
                bool considerKnownGridsAsAvailable) const override;
1894
1895
    PROJ_PRIVATE :
1896
1897
        //! @cond Doxygen_Suppress
1898
        PROJ_INTERNAL void
1899
        _exportToWKT(io::WKTFormatter *formatter)
1900
            const override; // throw(io::FormattingException)
1901
1902
    PROJ_INTERNAL bool _isEquivalentTo(
1903
        const util::IComparable *other,
1904
        util::IComparable::Criterion criterion =
1905
            util::IComparable::Criterion::STRICT,
1906
        const io::DatabaseContextPtr &dbContext = nullptr) const override;
1907
1908
    PROJ_INTERNAL void _exportToJSON(io::JSONFormatter *formatter)
1909
        const override; // throw(FormattingException)
1910
1911
    PROJ_INTERNAL static void
1912
    fixSteps(const crs::CRSNNPtr &concatOpSourceCRS,
1913
             const crs::CRSNNPtr &concatOpTargetCRS,
1914
             std::vector<CoordinateOperationNNPtr> &operationsInOut,
1915
             const io::DatabaseContextPtr &dbContext, bool fixDirectionAllowed);
1916
    //! @endcond
1917
1918
  protected:
1919
    PROJ_INTERNAL ConcatenatedOperation(const ConcatenatedOperation &other);
1920
    PROJ_INTERNAL explicit ConcatenatedOperation(
1921
        const std::vector<CoordinateOperationNNPtr> &operationsIn);
1922
1923
    PROJ_INTERNAL void _exportToPROJString(io::PROJStringFormatter *formatter)
1924
        const override; // throw(FormattingException)
1925
1926
    PROJ_INTERNAL CoordinateOperationNNPtr _shallowClone() const override;
1927
1928
    INLINED_MAKE_SHARED
1929
1930
  private:
1931
    PROJ_OPAQUE_PRIVATE_DATA
1932
    ConcatenatedOperation &
1933
    operator=(const ConcatenatedOperation &other) = delete;
1934
1935
    PROJ_INTERNAL
1936
    static void setCRSsUpdateInverse(CoordinateOperation *co,
1937
                                     const crs::CRSNNPtr &sourceCRS,
1938
                                     const crs::CRSNNPtr &targetCRS);
1939
};
1940
1941
// ---------------------------------------------------------------------------
1942
1943
class CoordinateOperationContext;
1944
/** Unique pointer of CoordinateOperationContext */
1945
using CoordinateOperationContextPtr =
1946
    std::unique_ptr<CoordinateOperationContext>;
1947
/** Non-null unique pointer of CoordinateOperationContext */
1948
using CoordinateOperationContextNNPtr = util::nn<CoordinateOperationContextPtr>;
1949
1950
/** \brief Context in which a coordinate operation is to be used.
1951
 *
1952
 * \remark Implements [CoordinateOperationFactory
1953
 * https://sis.apache.org/apidocs/org/apache/sis/referencing/operation/CoordinateOperationContext.html]
1954
 * from
1955
 * Apache SIS
1956
 */
1957
1958
class PROJ_GCC_DLL CoordinateOperationContext {
1959
  public:
1960
    //! @cond Doxygen_Suppress
1961
    PROJ_DLL virtual ~CoordinateOperationContext();
1962
    //! @endcond
1963
1964
    PROJ_DLL const io::AuthorityFactoryPtr &getAuthorityFactory() const;
1965
1966
    PROJ_DLL const metadata::ExtentPtr &getAreaOfInterest() const;
1967
1968
    PROJ_DLL void setAreaOfInterest(const metadata::ExtentPtr &extent);
1969
1970
    PROJ_DLL double getDesiredAccuracy() const;
1971
1972
    PROJ_DLL void setDesiredAccuracy(double accuracy);
1973
1974
    PROJ_DLL void setAllowBallparkTransformations(bool allow);
1975
1976
    PROJ_DLL bool getAllowBallparkTransformations() const;
1977
1978
    /** Specify how source and target CRS extent should be used to restrict
1979
     * candidate operations (only taken into account if no explicit area of
1980
     * interest is specified. */
1981
    enum class SourceTargetCRSExtentUse {
1982
        /** Ignore CRS extent */
1983
        NONE,
1984
        /** Test coordinate operation extent against both CRS extent. */
1985
        BOTH,
1986
        /** Test coordinate operation extent against the intersection of both
1987
           CRS extent. */
1988
        INTERSECTION,
1989
        /** Test coordinate operation against the smallest of both CRS extent.
1990
         */
1991
        SMALLEST,
1992
    };
1993
1994
    PROJ_DLL void setSourceAndTargetCRSExtentUse(SourceTargetCRSExtentUse use);
1995
1996
    PROJ_DLL SourceTargetCRSExtentUse getSourceAndTargetCRSExtentUse() const;
1997
1998
    /** Spatial criterion to restrict candidate operations. */
1999
    enum class SpatialCriterion {
2000
        /** The area of validity of transforms should strictly contain the
2001
         * are of interest. */
2002
        STRICT_CONTAINMENT,
2003
2004
        /** The area of validity of transforms should at least intersect the
2005
         * area of interest. */
2006
        PARTIAL_INTERSECTION
2007
    };
2008
2009
    PROJ_DLL void setSpatialCriterion(SpatialCriterion criterion);
2010
2011
    PROJ_DLL SpatialCriterion getSpatialCriterion() const;
2012
2013
    PROJ_DLL void setUsePROJAlternativeGridNames(bool usePROJNames);
2014
2015
    PROJ_DLL bool getUsePROJAlternativeGridNames() const;
2016
2017
    PROJ_DLL void setDiscardSuperseded(bool discard);
2018
2019
    PROJ_DLL bool getDiscardSuperseded() const;
2020
2021
    /** Describe how grid availability is used. */
2022
    enum class GridAvailabilityUse {
2023
        /** Grid availability is only used for sorting results. Operations
2024
         * where some grids are missing will be sorted last. */
2025
        USE_FOR_SORTING,
2026
2027
        /** Completely discard an operation if a required grid is missing. */
2028
        DISCARD_OPERATION_IF_MISSING_GRID,
2029
2030
        /** Ignore grid availability at all. Results will be presented as if
2031
         * all grids were available. */
2032
        IGNORE_GRID_AVAILABILITY,
2033
2034
        /** Results will be presented as if grids known to PROJ (that is
2035
         * registered in the grid_alternatives table of its database) were
2036
         * available. Used typically when networking is enabled.
2037
         */
2038
        KNOWN_AVAILABLE,
2039
    };
2040
2041
    PROJ_DLL void setGridAvailabilityUse(GridAvailabilityUse use);
2042
2043
    PROJ_DLL GridAvailabilityUse getGridAvailabilityUse() const;
2044
2045
    /** Describe if and how intermediate CRS should be used */
2046
    enum class IntermediateCRSUse {
2047
        /** Always search for intermediate CRS. */
2048
        ALWAYS,
2049
2050
        /** Only attempt looking for intermediate CRS if there is no direct
2051
         * transformation available. */
2052
        IF_NO_DIRECT_TRANSFORMATION,
2053
2054
        /* Do not attempt looking for intermediate CRS. */
2055
        NEVER,
2056
    };
2057
2058
    PROJ_DLL void setAllowUseIntermediateCRS(IntermediateCRSUse use);
2059
2060
    PROJ_DLL IntermediateCRSUse getAllowUseIntermediateCRS() const;
2061
2062
    PROJ_DLL void
2063
    setIntermediateCRS(const std::vector<std::pair<std::string, std::string>>
2064
                           &intermediateCRSAuthCodes);
2065
2066
    PROJ_DLL const std::vector<std::pair<std::string, std::string>> &
2067
    getIntermediateCRS() const;
2068
2069
    PROJ_DLL void
2070
    setSourceCoordinateEpoch(const util::optional<common::DataEpoch> &epoch);
2071
2072
    PROJ_DLL const util::optional<common::DataEpoch> &
2073
    getSourceCoordinateEpoch() const;
2074
2075
    PROJ_DLL void
2076
    setTargetCoordinateEpoch(const util::optional<common::DataEpoch> &epoch);
2077
2078
    PROJ_DLL const util::optional<common::DataEpoch> &
2079
    getTargetCoordinateEpoch() const;
2080
2081
    PROJ_DLL static CoordinateOperationContextNNPtr
2082
    create(const io::AuthorityFactoryPtr &authorityFactory,
2083
           const metadata::ExtentPtr &extent, double accuracy);
2084
2085
    PROJ_DLL CoordinateOperationContextNNPtr clone() const;
2086
2087
  protected:
2088
    PROJ_INTERNAL CoordinateOperationContext();
2089
    PROJ_INTERNAL
2090
    CoordinateOperationContext(const CoordinateOperationContext &);
2091
    INLINED_MAKE_UNIQUE
2092
2093
  private:
2094
    PROJ_OPAQUE_PRIVATE_DATA
2095
};
2096
2097
// ---------------------------------------------------------------------------
2098
2099
class CoordinateOperationFactory;
2100
/** Unique pointer of CoordinateOperationFactory */
2101
using CoordinateOperationFactoryPtr =
2102
    std::unique_ptr<CoordinateOperationFactory>;
2103
/** Non-null unique pointer of CoordinateOperationFactory */
2104
using CoordinateOperationFactoryNNPtr = util::nn<CoordinateOperationFactoryPtr>;
2105
2106
/** \brief Creates coordinate operations. This factory is capable to find
2107
 * coordinate transformations or conversions between two coordinate
2108
 * reference
2109
 * systems.
2110
 *
2111
 * \remark Implements (partially) CoordinateOperationFactory from \ref
2112
 * GeoAPI
2113
 */
2114
class PROJ_GCC_DLL CoordinateOperationFactory {
2115
  public:
2116
    //! @cond Doxygen_Suppress
2117
    PROJ_DLL virtual ~CoordinateOperationFactory();
2118
    //! @endcond
2119
2120
    PROJ_DLL CoordinateOperationPtr createOperation(
2121
        const crs::CRSNNPtr &sourceCRS, const crs::CRSNNPtr &targetCRS) const;
2122
2123
    PROJ_DLL std::vector<CoordinateOperationNNPtr>
2124
    createOperations(const crs::CRSNNPtr &sourceCRS,
2125
                     const crs::CRSNNPtr &targetCRS,
2126
                     const CoordinateOperationContextNNPtr &context) const;
2127
2128
    PROJ_DLL std::vector<CoordinateOperationNNPtr> createOperations(
2129
        const coordinates::CoordinateMetadataNNPtr &sourceCoordinateMetadata,
2130
        const crs::CRSNNPtr &targetCRS,
2131
        const CoordinateOperationContextNNPtr &context) const;
2132
2133
    PROJ_DLL std::vector<CoordinateOperationNNPtr> createOperations(
2134
        const crs::CRSNNPtr &sourceCRS,
2135
        const coordinates::CoordinateMetadataNNPtr &targetCoordinateMetadata,
2136
        const CoordinateOperationContextNNPtr &context) const;
2137
2138
    PROJ_DLL std::vector<CoordinateOperationNNPtr> createOperations(
2139
        const coordinates::CoordinateMetadataNNPtr &sourceCoordinateMetadata,
2140
        const coordinates::CoordinateMetadataNNPtr &targetCoordinateMetadata,
2141
        const CoordinateOperationContextNNPtr &context) const;
2142
2143
    PROJ_DLL static CoordinateOperationFactoryNNPtr create();
2144
2145
  protected:
2146
    PROJ_INTERNAL CoordinateOperationFactory();
2147
    INLINED_MAKE_UNIQUE
2148
2149
  private:
2150
    PROJ_OPAQUE_PRIVATE_DATA
2151
};
2152
2153
} // namespace operation
2154
2155
NS_PROJ_END
2156
2157
#endif //  COORDINATEOPERATION_HH_INCLUDED