diff --git a/DemUtility/README.md b/DemUtility/README.md new file mode 100644 index 0000000..b58e065 --- /dev/null +++ b/DemUtility/README.md @@ -0,0 +1,117 @@ +# DemUtility (`dem`) + +A command-line tool for managing Digital Elevation Model (DEM) databases produced or consumed by `Pmad.Cartography`. + +## Installation + +Build from source (requires .NET 10): + +``` +dotnet build DemUtility +``` + +Or publish a self-contained binary: + +``` +dotnet publish DemUtility -c Release -r win-x64 --self-contained +``` + +## Commands + +### `repack` – Re-compress a DEM database + +Creates a copy of a DEM database with a chosen compression format. Useful for converting downloaded archives (e.g. Zip) to faster formats such as ZSTD. + +``` +dem repack --source --target [options] +``` + +| Option | Short | Description | Default | +| ------ | ----- | ----------- | ------- | +| `--source` | `-s` | Source directory | *(required)* | +| `--target` | `-t` | Target directory | *(required)* | +| `--compression` | `-c` | `GZip`, `ZSTD`, `Brotli`, or `None` | `ZSTD` | +| `--max-cpu` | `-m` | Maximum CPU cores to use | all cores | +| `--keep` | `-k` | Skip files that already exist in target | `false` | + +**Example** + +``` +dem repack -s ./raw-srtm -t ./srtm-zstd -c ZSTD +``` + +--- + +### `index` – Build a database index + +Scans a local DEM directory and writes an `index.json` file listing all available cells. The index is required by `DemFileSystemStorage` for efficient tile lookup. + +``` +dem index --path +``` + +| Option | Short | Description | +| ------ | ----- | ----------- | +| `--path` | `-p` | Database directory | + +**Example** + +``` +dem index -p ./srtm-zstd +``` + +--- + +### `update-index` – Add missing checksums to an existing index + +Calculates and appends SHA-256 checksums for any cells that are listed in an existing `index.json` but do not yet have a checksum entry. + +``` +dem update-index --path +``` + +| Option | Short | Description | +| ------ | ----- | ----------- | +| `--path` | `-p` | Database directory | + +--- + +### `check` – Verify a database + +Reads a local or HTTP-hosted DEM database, reports its content and optionally verifies file integrity via SHA-256 checksums. + +``` +dem check (--path | --url ) [options] +``` + +| Option | Short | Description | +| ------ | ----- | ----------- | +| `--path` | `-p` | Local database directory | +| `--url` | `-u` | HTTP base URL of the database | +| `--verify` | `-v` | Verify SHA-256 checksums | +| `--sample` | `-n` | Number of cells to randomly sample (all cells when omitted) | + +**Examples** + +``` +# Check a local database and verify all checksums +dem check -p ./srtm-zstd --verify + +# Check a remote database and sample 100 random cells +dem check -u https://cdn.dem.pmad.net/SRTM1/ --verify --sample 100 +``` + +## Supported compression formats + +| Format | Extension | Notes | +| ------ | --------- | ----- | +| ZSTD | `.zst` | Recommended – best speed/size trade-off | +| GZip | `.gz` | Widest tool support | +| Brotli | `.br` | Best compression ratio | +| None | *(none)* | Uncompressed | + +## Dependencies + +- [Pmad.Cartography](https://www.nuget.org/packages/Pmad.Cartography) +- [System.CommandLine](https://www.nuget.org/packages/System.CommandLine) +- [Pmad.ProgressTracking](https://www.nuget.org/packages/Pmad.ProgressTracking) diff --git a/MapToolkit/Pmad.Cartography.csproj b/MapToolkit/Pmad.Cartography.csproj index caf540d..79fcdfa 100644 --- a/MapToolkit/Pmad.Cartography.csproj +++ b/MapToolkit/Pmad.Cartography.csproj @@ -31,7 +31,6 @@ - + - diff --git a/MapToolkit/README.md b/MapToolkit/README.md new file mode 100644 index 0000000..e544bf3 --- /dev/null +++ b/MapToolkit/README.md @@ -0,0 +1,115 @@ +# Pmad.Cartography + +[![NuGet](https://img.shields.io/nuget/v/Pmad.Cartography)](https://www.nuget.org/packages/Pmad.Cartography) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../LICENSE) + +A .NET library for Digital Elevation Model (DEM) processing. It provides elevation queries, contour line generation, hillshading and support for multiple data formats and on-demand HTTP data sources. + +## Installation + +``` +dotnet add package Pmad.Cartography +``` + +## Getting started + +### Query elevation from a well-known database + +```csharp +// Uses SRTM1 data hosted on cdn.dem.pmad.net (downloaded on demand and cached locally) +var database = WellKnownDatabases.GetSRTM1(); + +// Single point - bilinear interpolation +var elevation = await database.GetElevationAsync( + new Coordinates(51.509865, -0.118092), + DefaultInterpolation.Instance); + +// Load an area into memory as a float raster +var area = await database.CreateView( + new Coordinates(51, -1), + new Coordinates(52, 0)); +``` + +### Elevation contours + +```csharp +var contour = new ContourGraph(); +// 10-metre interval starting at 10 m +contour.Add(area, new ContourLevelGenerator(10, 10)); + +foreach (var line in contour.Lines) +{ + Console.WriteLine($"Level {line.Level}: {line.Points.Count} points"); +} +``` + +### Hillshading + +```csharp +// Each pixel of 'area' represents a 10x10-metre cell +var hillshader = new HillshaderFast(new Vector2D(10, 10)); + +// Returns an RGBA image where alpha encodes shadow intensity +Image img = hillshader.GetPixelsAlphaBelowFlat(area); +``` + +## Data sources + +The following open datasets are pre-configured in `WellKnownDatabases`: + +| Source | Resolution | License | Credits | +| -------- | -------------- | -------------- | ------- | +| SRTM1 | 1 arc second | Public Domain | NASA | +| SRTM15+ | 15 arc seconds | Public Domain | Tozer et al. | +| AW3D30 | 1 arc second | [See terms](https://cdn.dem.pmad.net/README.txt) | (c) JAXA | + +Data is fetched over HTTP from `cdn.dem.pmad.net` and cached locally. You can supply a custom cache path: + +```csharp +var database = WellKnownDatabases.GetSRTM1(localCache: @"C:\dem-cache"); +``` + +## File formats + +### Supported raster formats + +| Format | Read | Write | Notes | +| ---------- | :--: | :---: | ----- | +| ESRI ASCII | Yes | Yes | `float` only | +| DDC | Yes | Yes | Native format for this library | +| GeoTIFF | Yes | | WGS84 projection only | +| SRTM HGT | Yes | | 1 and 3 arc-second | + +### Supported compression wrappers + +| Format | Read | Write | Notes | +| ------ | :--: | :---: | ----- | +| ZSTD | Yes | Yes | Best storage/CPU trade-off (default) | +| GZip | Yes | Yes | Lowest CPU cost | +| Brotli | Yes | Yes | Best compression ratio | +| Zip | Yes | | Archive must contain a single file | + +## Key types + +| Type | Description | +| ---- | ----------- | +| `DemDatabase` | Main entry point - wraps a storage and provides async elevation/view queries | +| `WellKnownDatabases` | Factory helpers for the pre-configured CDN datasets | +| `DemDataCell` | In-memory raster tile with typed pixel values | +| `ContourGraph` | Builds a set of contour lines from a raster view | +| `ContourLevelGenerator` | Defines the interval and starting elevation for contour generation | +| `HillshaderFast` | Fast hillshading using the Zevenbergen-Thorne gradient algorithm | +| `HillshaderClassic` | Reference hillshader (slower, same visual output) | +| `HillshaderIgor` | Alternative hillshader with a different lighting model | +| `DefaultInterpolation` | Bilinear elevation interpolation between raster pixels | +| `Coordinates` | WGS84 latitude/longitude coordinate pair | +| `DemFileSystemStorage` | Reads a DEM database from a local directory | +| `DemHttpStorage` | Downloads DEM tiles on demand from an HTTP server with local caching | + +## Dependencies + +- [Pmad.Geometry](https://www.nuget.org/packages/Pmad.Geometry) +- [SixLabors.ImageSharp](https://www.nuget.org/packages/SixLabors.ImageSharp) +- [BitMiracle.LibTiff.NET](https://www.nuget.org/packages/BitMiracle.LibTiff.NET) +- [ZstdSharp.Port](https://www.nuget.org/packages/ZstdSharp.Port) +- [GeoJSON.Text](https://www.nuget.org/packages/GeoJSON.Text) diff --git a/Pmad.Cartography.Drawing/Pmad.Cartography.Drawing.csproj b/Pmad.Cartography.Drawing/Pmad.Cartography.Drawing.csproj index df569df..3696c45 100644 --- a/Pmad.Cartography.Drawing/Pmad.Cartography.Drawing.csproj +++ b/Pmad.Cartography.Drawing/Pmad.Cartography.Drawing.csproj @@ -27,7 +27,7 @@ - + diff --git a/Pmad.Cartography.Drawing/README.md b/Pmad.Cartography.Drawing/README.md new file mode 100644 index 0000000..b5bebf7 --- /dev/null +++ b/Pmad.Cartography.Drawing/README.md @@ -0,0 +1,114 @@ +# Pmad.Cartography.Drawing + +[![NuGet](https://img.shields.io/nuget/v/Pmad.Cartography.Drawing)](https://www.nuget.org/packages/Pmad.Cartography.Drawing) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../LICENSE) + +A .NET library for rendering topographic maps and contour overlays. It combines `Pmad.Cartography` (DEM/contour data) with `Pmad.Drawing` (vector output) to produce publication-quality maps in SVG, PNG/WebP and PDF. + +## Installation + +``` +dotnet add package Pmad.Cartography.Drawing +``` + +## Getting started + +### Render contour lines + +```csharp +// Build contours from a DEM view +var contour = new ContourGraph(); +contour.Add(area, new ContourLevelGenerator(10, 10)); + +// Render to any IDrawSurface +Render.ToSvg("contours.svg", new Vector2D(1024, 1024), surface => +{ + var renderer = new ContourRender(surface); + renderer.Render(contour, projectionArea, hillshadeImage); +}); +``` + +### Render a full topographic map + +```csharp +// Populate map data (roads, forests, water, buildings, etc.) +var data = new TopoMapRenderData +{ + Data = myTopoMapData, // implements ITopoMapData + Img = hillshadeImage // optional pre-computed hillshade +}; + +var proj = new NoProjectionArea(origin, new Vector2D(width, height), scale); + +Render.ToSvgTiled("map.svg", proj.Size, SvgFallBackFormats.Webp, + lod1: surface => new TopoMapRender(data, proj).Render(surface), + lod2: surface => new TopoMapRender(data, proj).RenderLod2(surface), + lod3: surface => new TopoMapRender(data, proj).RenderLod3(surface)); +``` + +### Export as PDF + +```csharp +var pdfRender = new TopoMapPdfRender(data, proj); +pdfRender.Render("map.pdf"); +``` + +## Map data model + +`ITopoMapData` / `TopoMapData` carries all vector layers that the renderer understands: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| `DemDataCell` | `IDemDataView` | Elevation raster (required) | +| `Roads` | `Dictionary` | Road network by category | +| `Bridges` | `Dictionary` | Bridge segments | +| `Railways` | `MultiPath` | Rail lines | +| `Powerlines` | `MultiPath` | Power line routes | +| `ForestPolygons` | `MultiPolygon` | Forested areas | +| `RockPolygons` | `MultiPolygon` | Rock/cliff areas | +| `WaterPolygons` | `MultiPolygon` | Water bodies | +| `BuildingPolygons` | `MultiPolygon` | Building footprints | +| `FortPolygons` | `MultiPolygon` | Fortification areas | +| `Names` | `List` | Named locations with type and position | +| `Icons` | `List` | Point-of-interest icons | +| `PlottedPoints` | `List` | Labelled elevation spot heights | + +### Map metadata + +```csharp +var metadata = new TopoMapMetadata( + attribution: "Map data (c) OpenStreetMap contributors", + title: "My Topographic Map", + licenseNotice: "CC BY-SA 4.0", + exportCreator: "MyApp 1.0", + upperTitle: "Sheet 1"); +``` + +## Level-of-detail rendering + +`TopoMapRender` exposes three LOD methods that progressively simplify the map for smaller zoom levels: + +| Method | Detail level | Typical use | +| ------ | ------------ | ----------- | +| `Render` | Full detail | Maximum zoom | +| `RenderLod2` | Reduced | Medium zoom | +| `RenderLod3` | Minimal | Overview zoom | + +## Key types + +| Type | Description | +| ---- | ----------- | +| `ContourRender` | Draws a `ContourGraph` onto an `IDrawSurface`, with optional hillshade underlay | +| `ContourRenderStyle` | Default contour styling (thin lines every 10 m, bold every 50 m) | +| `TopoMapRender` | Full topographic map renderer | +| `TopoMapPdfRender` | PDF-specific renderer with page layout and legend | +| `TopoMapStyle` | Colour palette and style factory for all map layers | +| `ColorPalette` | Default colour values used by `TopoMapStyle` | +| `LegendRender` | Draws the map legend | +| `NoProjectionArea` | Simple pixel-to-coordinate projection for flat/local maps | + +## Dependencies + +- [Pmad.Cartography](https://www.nuget.org/packages/Pmad.Cartography) +- [Pmad.Drawing](https://www.nuget.org/packages/Pmad.Drawing) +- [Pmad.ProgressTracking](https://www.nuget.org/packages/Pmad.ProgressTracking) diff --git a/Pmad.Drawing/README.md b/Pmad.Drawing/README.md index 3acec4c..7177741 100644 --- a/Pmad.Drawing/README.md +++ b/Pmad.Drawing/README.md @@ -1 +1,110 @@ -# Pmad.Drawing \ No newline at end of file +# Pmad.Drawing + +[![NuGet](https://img.shields.io/nuget/v/Pmad.Drawing)](https://www.nuget.org/packages/Pmad.Drawing) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../LICENSE) + +A .NET vector drawing library that exposes a single `IDrawSurface` API and supports multiple output backends: **SVG**, **PNG/WebP** (via ImageSharp) and **PDF** (via PdfSharpCore). Tiled output for web maps (Leaflet-compatible) is also supported. + +## Installation + +``` +dotnet add package Pmad.Drawing +``` + +## Getting started + +### Render to SVG + +```csharp +Render.ToSvg("output.svg", new Vector2D(800, 600), surface => +{ + var fill = new SolidColorBrush(Color.LightBlue); + var stroke = new Pen(new SolidColorBrush(Color.DarkBlue), 2); + var style = surface.AllocateStyle(fill, stroke); + + surface.DrawPolygon(new[] { myPoints }, style); + surface.DrawPolyline(myLine, style); +}); +``` + +### Render to PNG + +```csharp +Render.ToPng("output.png", new Vector2D(800, 600), surface => +{ + // same drawing calls as SVG +}); +``` + +### Render to PDF + +```csharp +Render.ToPdf("output.pdf", PaperSize.A4Landscape, surface => +{ + // same drawing calls +}); +``` + +### Generate map tiles (Leaflet-compatible) + +```csharp +TilingInfos info = Render.ToSvgTiled( + "tiles/map.svg", + new Vector2D(4096, 4096), + SvgFallBackFormats.Webp, + drawLod1: surface => { /* full-detail drawing */ }, + drawLod2: surface => { /* reduced-detail drawing */ }); +``` + +You can also tile an existing `Image` directly: + +```csharp +TilingInfos info = ImageTiler.DefaultToWebp(fullImage, "tiles/"); +``` + +## Drawing API overview + +All output backends implement `IDrawSurface`: + +| Method | Description | +| ------ | ----------- | +| `AllocateStyle(fill, pen)` | Create a reusable fill/stroke style | +| `AllocateTextStyle(...)` | Create a reusable text style (font, size, colour, anchor) | +| `AllocateIcon(size, draw)` | Create a reusable icon defined by a drawing callback | +| `DrawPolygon(paths, style)` | Filled/stroked polygon (with holes via multiple paths) | +| `DrawPolyline(points, style)` | Open polyline | +| `DrawCircle(center, radius, style)` | Circle | +| `DrawArc(center, radius, start, sweep, style)` | Arc | +| `DrawTextPath(points, text, style)` | Text flowing along a path | +| `DrawText(point, text, style)` | Text at a fixed position | +| `DrawIcon(center, icon)` | Pre-allocated icon | +| `DrawImage(image, pos, size, alpha)` | Raster image | +| `DrawRoundedRectangle(tl, br, style, radius)` | Rounded rectangle | + +### Brushes + +| Type | Description | +| ---- | ----------- | +| `SolidColorBrush` | Uniform RGBA colour | +| `VectorBrush` | Pattern brush defined by a drawing callback | + +### Memory surface and scaling + +`MemorySurface` records all drawing operations so they can be replayed at a different scale or into a different backend – useful for generating multiple zoom levels from a single drawing pass. + +## Output backends + +| Backend | Class | Notes | +| ------- | ----- | ----- | +| SVG | `SvgSurface` | Inline CSS styles, external image references | +| PNG / WebP / JPEG | `ImageSurface` | Rasterised via ImageSharp | +| PDF | `PdfSurface` | Single-page PDF via PdfSharpCore | +| Memory | `MemorySurface` | Captures operations for later replay or scaling | + +## Dependencies + +- [Pmad.Geometry](https://www.nuget.org/packages/Pmad.Geometry) +- [SixLabors.ImageSharp](https://www.nuget.org/packages/SixLabors.ImageSharp) +- [SixLabors.ImageSharp.Drawing](https://www.nuget.org/packages/SixLabors.ImageSharp.Drawing) +- [PdfSharpCore](https://www.nuget.org/packages/PdfSharpCore) +- [Pmad.ProgressTracking](https://www.nuget.org/packages/Pmad.ProgressTracking) diff --git a/README.md b/README.md index e873780..ca20f1d 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,21 @@ -# Pmad.Cartography +# MapKit -## Pmad.Cartography -A simple and read-to-use Digital Elevation Model for everyone based on Open Data with minimalist credits +A collection of .NET libraries and tools for map processing, Digital Elevation Models (DEM) and map rendering. -### Digital Elevation Model sources +## Packages -| Source | Resolution | License | URL | Credits | -| ------ | ------------- | ------------- | --- | --- | -| SRTM1 | 1 arc second | Public Domain | https://cdn.dem.pmad.net/SRTM1/ | NASA | -| SRTM15+| 15 arc second | Public Domain | https://cdn.dem.pmad.net/SRTM15Plus/ | Tozer, B. , D. T. Sandwell, W. H. F. Smith, C. Olson, J. R. Beale, and P. Wessel | -| AW3D30 | 1 arc second | [See terms](https://cdn.dem.pmad.net/README.txt) | https://cdn.dem.pmad.net/AW3D30/ | � JAXA | +| Package | NuGet | Description | +| ------- | ----- | ----------- | +| [Pmad.Cartography](MapToolkit/) | [![NuGet](https://img.shields.io/nuget/v/Pmad.Cartography)](https://www.nuget.org/packages/Pmad.Cartography) | DEM processing: elevation queries, contour lines, hillshading, file I/O | +| [Pmad.Drawing](Pmad.Drawing/) | [![NuGet](https://img.shields.io/nuget/v/Pmad.Drawing)](https://www.nuget.org/packages/Pmad.Drawing) | Vector drawing API with SVG, PNG/WebP and PDF backends | +| [Pmad.Cartography.Drawing](Pmad.Cartography.Drawing/) | [![NuGet](https://img.shields.io/nuget/v/Pmad.Cartography.Drawing)](https://www.nuget.org/packages/Pmad.Cartography.Drawing) | Topographic map rendering built on top of the two libraries above | -```csharp -var database = WellKnownDatabases.GetSRTM1(); +## Tools -// Singe point -var elevation = await database.GetElevationAsync(new Coordinates(51.509865, -0.118092), DefaultInterpolation.Instance); +| Tool | Description | +| ---- | ----------- | +| [DemUtility](DemUtility/) | CLI tool (`dem`) for managing DEM databases: indexing, repacking, integrity checks | -// Area -var area = await demDatabase.CreateView(new Coordinates(51, -1), new Coordinates(52, 0)); -``` +## License -### Elevation contours - -```csharp -var contour = new ContourGraph(); -contour.Add(area, new ContourLevelGenerator(10, 10)); // 10 meters elevation interval from 10 -``` - -### Hillshading - -```csharp -var img = new HillshaderFast(new Vector2D(10, 10)) // Assume each pixel of area is 10x10 meters - .GetPixelsAlphaBelowFlat(area); -``` - -### File formats - -#### Supported data formats - -| Format | Read | Write | Remarks | -| ---------- | ---- | ----- | ----------------------------------- | -| ESRI ASCII | Yes | Yes | float only | -| DDC | Yes | Yes | Format specific to Pmad.Cartography | -| GeoTIFF | Yes | No | WSG84 projection Only | -| SRTM | Yes | No | 3 and 1 arc second | - -#### Supported compression formats - -Most DEM files requires a lot of disk space. To reduce the size of the files, the following compression formats are supported: - -| Format | Read | Write | Remarks | -| ---------- | ---- | ----- | ----------------------------------- | -| ZSTD | Yes | Yes | Best compromise storage/CPU cost | -| GZIP | Yes | Yes | Lowest CPU cost | -| Brotli | Yes | Yes | Best compression | -| Zip | Yes | No | Zip must contains only one file | - -## Pmad.Cartography.Drawing - -A simple topographic map rendering toolkit. - -Drawing API is still in development, it may change in the future. +MIT - see [LICENSE](LICENSE) for details.