diff --git a/MapWinGIS6.slnx b/MapWinGIS6.slnx index b85e859..4c7f41c 100644 --- a/MapWinGIS6.slnx +++ b/MapWinGIS6.slnx @@ -11,6 +11,9 @@ + + + diff --git a/README.md b/README.md index d7f5b27..b8036e3 100644 --- a/README.md +++ b/README.md @@ -71,8 +71,12 @@ For additional configurations, dependency features, and troubleshooting, see |---|---| | `src/MapWinGIS.Core/` | The core engine. Public headers in `include/mapwingis/` | | `tests/MapWinGIS.Core.Tests/` | C++ unit tests (GoogleTest) | +| `samples/Cpp/` | Buildable native C++ examples | | `build/` | Shared MSBuild props, vcpkg triplets and scripts | -| `docs/` | Build, architecture, coding, porting and testing documentation | +| `docs/` | Build, architecture, coding, GDAL integration, porting and testing documentation | + +See [GDAL integration](docs/gdal-integration.md) for GDAL setup, API examples, +progress handling, migration notes, and limitations. ## License diff --git a/docs/TESTING.md b/docs/TESTING.md index 4915835..c7d6544 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -43,3 +43,5 @@ up automatically). tests. Each has four polygons in EPSG:28992, all five field types, null values, and UTF-8 names. Tests edit their own generated datasets. - Wrap expected GDAL noise in `GdalEnvironment::QuietScope`. +- Tests use local generated data and do not require network access by default. + Set `MWG_RUN_NETWORK_GDAL_TESTS=1` to enable the public `/vsicurl/` COG test. diff --git a/docs/gdal-integration.md b/docs/gdal-integration.md new file mode 100644 index 0000000..c7f4ebc --- /dev/null +++ b/docs/gdal-integration.md @@ -0,0 +1,200 @@ +# GDAL integration + +MapWinGIS6 provides a native C++20 interface to GDAL through +`MapWinGIS.Core.dll`. `MwGdalCore` implements GDAL algorithm execution; +`MapWinGIS.Core` configures GDAL's runtime data paths and exposes the public +headers under `mapwingis/gdal/`. The Core DLL does not use COM, ATL, or MFC. + +## Requirements and runtime setup + +MapWinGIS6 requires GDAL 3.12.4 or later. The vcpkg manifest pins the version +used by this repository. GDAL headers and libraries come from vcpkg; do not +install another GDAL SDK beside the application. See [GDAL versioning](gdal-version.md) +and [Building MapWinGIS6](BUILDING.md) for dependency and build instructions. + +`GdalEnvironment::Initialize()` registers drivers once and points GDAL and PROJ +to the runtime data deployed beside `MapWinGIS.Core.dll`. Call it before direct +GDAL use; the MapWinGIS GDAL APIs initialize the environment as needed. The +driver set depends on the vcpkg build features. Check availability at runtime +with `GdalEnvironment::HasRasterDriver()` or `HasVectorDriver()`. An absent +driver or unsupported algorithm produces GDAL diagnostics; it is not silently +substituted. + +The DLL API exchanges C++ standard-library types across the DLL boundary. +Consumers must use the same MSVC toolset and CRT as the Core DLL. + +## Generic algorithms and typed options + +Use `GdalAlgorithmRunner` when you need an algorithm supported by the +installed GDAL build. Its path is the GDAL algorithm name, and +`UsageAsJson()` exposes the installed algorithm's own argument metadata: + +```cpp +mwg::GdalEnvironment::Initialize(); +mwg::GdalAlgorithmRunner runner("raster convert"); +const std::string metadata = runner.UsageAsJson(); +``` + +Pass arguments with the typed `SetArgument()` overloads or +`ParseCommandLineArgs()`, then call `Run()`. The runner validates arguments +against GDAL's metadata and captures warnings and failures in `Errors()`. +`Result()` returns a snapshot without transferring output datasets; +`TakeOutputDataset()` transfers ownership of an output dataset. + +For common operations, use a typed options structure. This example converts +an input raster to GeoTIFF and reports captured diagnostics on failure: + +```cpp +mwg::RasterConvertOptions options; +options.input = inputPath; +options.output = outputPath; +options.outputFormat = "GTiff"; +options.creationOptions = {"COMPRESS=LZW"}; + +mwg::GdalAlgorithmRunner runner("raster convert"); +if (!mwg::ConfigureGdalAlgorithm(runner, options.ToArgs()) || !runner.Run()) +{ + const auto result = runner.Result(); + std::cerr << result.DetailedErrorMsg() << '\n'; +} +``` + +The typed structures cover raster conversion, clipping, reprojection, +mosaicking, calculation and overviews, plus vector conversion and clipping. +They translate values to GDAL arguments; GDAL remains responsible for +algorithm-specific validation, driver support and defaults. To see the current +option list for an installed algorithm, inspect `UsageAsJson()` instead of +copying an option list into application documentation. + +## Progress and cancellation + +Progress callbacks execute synchronously on the thread running GDAL. Return +`false` to cancel. A cancellation token can also be cancelled from another +thread and must remain alive until the operation returns: + +```cpp +mwg::GdalCancellationToken cancellation; +const auto progress = [](double fraction, std::string_view message) +{ + std::cout << fraction << ": " << message << '\n'; + return true; +}; + +const bool succeeded = runner.Run(progress, &cancellation); +``` + +Use the token with `WriteCog()` or `RunPipeline()` in the same way. Not every +GDAL algorithm reports progress, so cancellation may not interrupt those +algorithms promptly. Cancellation can leave partial output files. Callbacks +must not start another GDAL operation or wait on a thread that needs the GDAL +execution lock; callback exceptions are returned as operation failures. + +## Errors and logging + +Runner and convenience-operation results own their diagnostic lists. +`Succeeded()` is true only if GDAL execution and finalization succeed. +`LastErrorCode()` and `ErrorMsg()` select the last failure or fatal diagnostic; +warnings alone do not make a successful operation fail. Use +`DetailedErrorMsg()` or `AllErrors()` when the full diagnostic context matters. + +Install an optional process-wide handler with +`GdalEnvironment::SetLogHandler()`. Diagnostics are delivered on the thread +that raises them. Handlers must not re-enter GDAL or wait for GDAL work on +another thread. The callback boundary does not permit exceptions to cross into +GDAL; captured logger exceptions are rethrown by the operation after GDAL +returns. + +## In-memory datasets and pipelines + +`RunPipeline()` passes each step's output dataset directly to the next step. +Later steps omit the `input` argument. Keep the returned result alive while +using its output dataset; it retains intermediate datasets required by VRT +outputs. Choose output formats such as `MEM` for in-memory raster processing +or `VRT` for virtual datasets when the algorithm supports them: + +```cpp +mwg::RasterConvertOptions options; +options.input = inputPath; +options.outputFormat = "MEM"; + +mwg::GdalPipelineStep step{ + {"raster", "convert"}, + options.ToArgs() +}; +const auto result = mwg::RunPipeline({step}); +``` + +`WriteCog()` is the convenience operation for Cloud-Optimized GeoTIFF output. +The COG driver and the GDAL build determine which creation options are +available. VRT files can refer to source datasets; keep their sources +available for as long as the VRT needs them. + +## Cloud and virtual filesystem paths + +GDAL virtual filesystem paths such as `/vsicurl/`, `/vsis3/`, `/vsizip/`, +`/vsiaz/`, and `/vsimem/` are accepted as UTF-8 paths when the selected driver +supports them. Cloud access depends on the GDAL build, network access and +provider configuration. Use GDAL's supported credential mechanisms or +configuration options. `GdalConfig::SetOption()` changes process-wide +configuration; `ScopedGdalConfigOption` restores the previous value at scope +exit but does not isolate concurrent changes to the same option. Never put +credentials in paths, source code, tests or logs. + +## GDAL 3 axis order + +GDAL 3 honors the axis order defined by a coordinate reference system's +authority when using OGR spatial-reference and coordinate-transformation APIs. +For example, EPSG:4326 is latitude then longitude according to its authority +definition. MapWinGIS6 does not install a global axis-order override; GDAL +algorithms apply their own documented behavior. + +For direct OGR transformations that must use traditional GIS X/Y order, set +the strategy on the spatial reference objects before creating the +transformation: + +```cpp +OGRSpatialReference srs; +srs.importFromEPSG(4326); +srs.SetAxisMappingStrategy(OAMS_TRADITIONAL_GIS_ORDER); +``` + +Apply the same intended convention to both source and target spatial +references. This is an explicit per-object choice, not a process-wide +compatibility setting. Check the selected algorithm's usage metadata for +algorithm-specific CRS options. + +## Migration and examples + +MapWinGIS5's COM `GdalUtils` is not yet exposed by MapWinGIS6's ActiveX layer. +Use the native runner and typed options for new C++ code. A deprecated native +`GdalUtils` bridge is available for gradual migration; it is not +binary-compatible with the v5 COM object. See [GDAL migration](gdal-migration.md) +for operation examples and API differences. + +The solution builds the runnable C++ example +[`samples/Cpp/translate.cpp`](../samples/Cpp/translate.cpp). Run it with +`bin\Debug\x64\translate.exe `. +There is no C# sample yet: the Core DLL has no managed binding or C ABI, and +the ActiveX layer does not expose the GDAL API to C#. + +## Limitations and troubleshooting + +- Driver and algorithm availability varies with the vcpkg feature set. Check + `HasRasterDriver()`, `HasVectorDriver()`, and `UsageAsJson()` at runtime. +- The runner serializes its GDAL algorithm calls, but returned datasets and + direct GDAL calls are not covered by that lock. Synchronize access to shared + datasets and process-wide configuration yourself. +- Native Core objects are not thread-safe unless their API says otherwise. + Progress and logging callbacks run synchronously on the operation thread. +- If initialization reports missing GDAL or PROJ data, rebuild with runtime + data deployment enabled. The data directories are placed beside the DLL; + do not set `GDAL_DATA` or `PROJ_LIB` as a workaround. +- If a cloud path fails, confirm the driver, protocol support, credentials, + network access and GDAL configuration for the installed build. +- If a conversion fails, inspect all captured diagnostics; an installed GDAL + build may not include the requested output driver or algorithm. + +The automated tests create small raster and vector fixtures under temporary +directories and remove them after each test. They do not depend on network +data unless `MWG_RUN_NETWORK_GDAL_TESTS=1` is set for the opt-in public COG +test. diff --git a/samples/Cpp/Translate.vcxproj b/samples/Cpp/Translate.vcxproj new file mode 100644 index 0000000..4662018 --- /dev/null +++ b/samples/Cpp/Translate.vcxproj @@ -0,0 +1,63 @@ + + + + + + Debug + Win32 + + + Debug + x64 + + + Release + Win32 + + + Release + x64 + + + + + {2B6A9A3B-0C5E-4E6E-9E31-3E8F5A2D1C03} + MapWinGISTranslateSample + TranslateSample + translate + + + + + + Application + + + + + + + + + + + $(MwgRepoRoot)src\MapWinGIS.Core\include;%(AdditionalIncludeDirectories) + + + Console + + + + + + + + + + {2B6A9A3B-0C5E-4E6E-9E31-3E8F5A2D1C01} + + + + + + diff --git a/samples/Cpp/translate.cpp b/samples/Cpp/translate.cpp new file mode 100644 index 0000000..c623d56 --- /dev/null +++ b/samples/Cpp/translate.cpp @@ -0,0 +1,46 @@ +// SPDX-License-Identifier: MPL-2.0 + +/** + * @file translate.cpp + * @brief Converts a raster dataset with the typed GDAL API. + */ +#include +#include +#include + +#include "mapwingis/gdal/GdalAlgorithmRunner.h" +#include "mapwingis/gdal/GdalEnvironment.h" +#include "mapwingis/gdal/GdalTypedOptions.h" + +int wmain(const int argc, wchar_t* argv[]) +{ + if (argc != 3) + { + std::wcerr << L"Usage: translate \n"; + return 2; + } + + try + { + mwg::GdalEnvironment::Initialize(); + + mwg::RasterConvertOptions options; + options.input = std::filesystem::path(argv[1]); + options.output = std::filesystem::path(argv[2]); + options.outputFormat = "GTiff"; + + mwg::GdalAlgorithmRunner runner("raster convert"); + if (!mwg::ConfigureGdalAlgorithm(runner, options.ToArgs()) || !runner.Run()) + { + std::cerr << runner.Result().DetailedErrorMsg() << '\n'; + return 1; + } + + return 0; + } + catch (const std::exception& error) + { + std::cerr << error.what() << '\n'; + return 1; + } +} diff --git a/tests/MapWinGIS.Core.Tests/GdalTypedOptionsTests.cpp b/tests/MapWinGIS.Core.Tests/GdalTypedOptionsTests.cpp index 60c2f50..a785197 100644 --- a/tests/MapWinGIS.Core.Tests/GdalTypedOptionsTests.cpp +++ b/tests/MapWinGIS.Core.Tests/GdalTypedOptionsTests.cpp @@ -368,6 +368,28 @@ TEST(GdalTypedOptions, ConvertsRasterToPngAndReturnsTheOutputDataset) EXPECT_TRUE(std::filesystem::exists(output)); } +TEST(GdalTypedOptions, ReportsUnavailableOutputDriver) +{ + GdalEnvironment::Initialize(); + GdalEnvironment::QuietScope quiet; + test::TempDirectory directory; + + RasterConvertOptions options; + options.input = test::MakeRaster(directory.Path()); + options.output = directory.Path() / "unavailable-driver.out"; + options.outputFormat = "MWG_DRIVER_NOT_INSTALLED"; + + GdalAlgorithmRunner runner("raster convert"); + const bool configured = ConfigureGdalAlgorithm(runner, options.ToArgs()); + if (configured) + EXPECT_FALSE(runner.Run()); + + EXPECT_FALSE(runner.Result().Succeeded()); + ASSERT_FALSE(runner.Errors().empty()); + EXPECT_FALSE(runner.Errors().back().message.empty()); + EXPECT_FALSE(std::filesystem::exists(options.output)); +} + TEST(GdalTypedOptions, ConvertsVectorLayersAndPreservesAttributes) { test::TempDirectory directory;