Skip to content

Add README files #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jetelain merged 1 commit into from
May 2, 2026
Merged

Add README files #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 117 additions & 0 deletions DemUtility/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <dir> --target <dir> [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 <dir>
```

| 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 <dir>
```

| 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 <dir> | --url <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)
3 changes: 1 addition & 2 deletions MapToolkit/Pmad.Cartography.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,6 @@
<PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All" />
</ItemGroup>
<ItemGroup>
<None Include="..\README.md" Pack="true" PackagePath="\" />
<None Include="README.md" Pack="true" PackagePath="\" />
</ItemGroup>

</Project>
115 changes: 115 additions & 0 deletions MapToolkit/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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<float>(
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<Rgba32> 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<T>` | 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)
2 changes: 1 addition & 1 deletion Pmad.Cartography.Drawing/Pmad.Cartography.Drawing.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
<PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All" />
</ItemGroup>
<ItemGroup>
<None Include="..\README.md" Pack="true" PackagePath="\" />
<None Include="README.md" Pack="true" PackagePath="\" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\Pmad.Drawing\Pmad.Drawing.csproj" />
Expand Down
114 changes: 114 additions & 0 deletions Pmad.Cartography.Drawing/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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<TopoMapPathType, MultiPath>` | Road network by category |
| `Bridges` | `Dictionary<TopoMapPathType, MultiPath>` | 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<TopoLocation>` | Named locations with type and position |
| `Icons` | `List<TopoIcon>` | Point-of-interest icons |
| `PlottedPoints` | `List<DemDataPoint>` | 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)
Loading
Loading