Chart Manager
Download and work with S-57 electronic nautical charts (ENCs) in your Go applications or from the command line. This library currently supports NOAA S-57 charts.
Experimental software for learning and development only. This project explores AI-assisted development with complex marine chart standards.
⚠️ Not for production use or actual navigation.
Documentation as Specification: This documentation serves as a living specification that drives development. We strive to ensure documented features are implemented and working, but we're actively refining our development and testing workflows. Some features may be in progress.
Not affiliated with any chart provider. Independent third-party library accessing publicly available S-57 chart data.
What Does It Do?
This is a chart manager library. Currently provides access to NOAA's Electronic Navigational Charts (ENCs), with architecture designed to support additional chart providers.
Instead of downloading 30GB of charts you'll never use, this library lets you:
- Find charts for any location - San Francisco, Chesapeake Bay, New York Harbor, anywhere
- Download only what you need - just the charts covering your area
- Keep them updated - automatic checks for new chart versions
- Use them in your code - parse depths, buoys, hazards, shorelines, anything on the chart
Two ways to use it:
- Go library - The main component. Embed chart management in your application.
- CLI tool - Optional utility for exploring charts, managing the cache, or downloading charts for offline use.
The CLI is a companion for managing what the library does - you can use the library without it.
Current chart source: NOAA's Office of Coast Survey - US government charts used by ships worldwide. The architecture supports adding additional S-57 chart providers in the future.
What's This For?
This is a learning project exploring how to work with S-57 chart data programmatically. Useful if you're interested in:
- Learning how marine chart data works
- Experimenting with chart rendering
- Understanding navigation data formats (S-57 standard)
- Exploring chart collections (currently NOAA)
- Building proof-of-concept marine tools
Not production-ready, but functional enough to learn from and experiment with.
Why This Approach?
Working with NOAA charts usually means downloading gigabytes of data or dealing with complex formats. This tool simplifies that:
- Download just the charts you need, not all 30GB
- Simple API - specify an area and zoom level
- Automatic caching and updates
- Works from Go code or command line
Makes NOAA chart data easier to experiment with and learn from.
Query vs Download
The chart manager gives you control over when charts are downloaded:
Query Catalog (Metadata Only)
Query the catalog to see what charts are available without downloading them:
// Query catalog (no downloads)
entries := mgr.QueryCatalog(viewport)
for _, entry := range entries {
fmt.Printf("%s - %.1f MB\n", entry.Name, entry.SizeMB)
}
Use when:
- Browsing available charts
- Planning downloads
- Showing preview information to users
- Working on metered/limited connections
- Building chart selection interfaces
CLI: Use query
command
Download Charts
Download and load charts on-demand:
// Load charts (downloads on-demand)
charts, _ := mgr.GetChartsForViewport(viewport, 12)
for _, chart := range charts {
features := chart.FeaturesInBounds(viewport)
// ... render features
}
Use when:
- Rendering charts
- Extracting features
- Analyzing chart data
- Ready to work with actual chart content
CLI: Use download
command
How It Works
import (
"github.com/beetlebugorg/chartmanager/pkg/chartmanager"
"github.com/beetlebugorg/s57/pkg/s57"
)
// Create manager (auto-downloads catalog if needed)
mgr, _ := chartmanager.NewChartManager(
chartmanager.DefaultChartManagerOptions())
// Define viewport for San Francisco Bay
viewport := s57.Bounds{
MinLon: -122.5, MaxLon: -122.0,
MinLat: 37.5, MaxLat: 38.0,
}
// Option 1: Query first (no download)
entries := mgr.QueryCatalog(viewport)
fmt.Printf("Found %d charts, %.1f MB total\n", len(entries), totalSize(entries))
// Option 2: Load charts directly (downloads on-demand)
charts, _ := mgr.GetChartsForViewport(viewport, 12)
Architecture
This library builds on the s57 parser and adds chart lifecycle management:
- s57 parser - Parses S-57 format (ISO 8211, geometry, features)
- chartmanager - Manages chart lifecycle (catalog, download, cache, index)
The separation keeps parsing concerns independent from operational concerns.
Chart Manager Workflow
- Catalog Download - Fetch NOAA catalog XML (once, cached with ETag)
- Spatial Indexing - Build R-tree of all 6500+ chart boundaries
- Viewport Query - Find charts covering your region (O(log n))
- Lazy Download - Download and parse only needed charts
- LRU Caching - Keep recently-used charts in memory
Why This Approach?
Traditional approach:
❌ Download all 6500 charts = 30GB storage, hours of downloading
This approach:
✅ Download catalog = 90MB, 1-2 seconds
✅ Download charts on-demand = Only what you need
✅ Cache locally = Instant subsequent access
Next Steps
- Installation - Get started with the library or CLI
- CLI Reference - Command-line tool documentation
- API Reference - Complete API documentation
- Examples - Code examples and common patterns