Skip to main content

Installation

Requirements​

  • Go 1.21 or later
  • Internet connection (for downloading NOAA catalog and charts)

Install the Package​

go get github.com/beetlebugorg/chartmanager

Install the CLI Tool​

go install github.com/beetlebugorg/chartmanager/cmd/chartmanager@latest

Verify installation:

chartmanager version
# Output shows version, commit, build date, Go version, and platform

Verify Library Installation​

Create a simple test program:

package main

import (
    "fmt"
    "log"

    "github.com/beetlebugorg/chartmanager/pkg/chartmanager"
)

func main() {
    opts := chartmanager.DefaultChartManagerOptions()
    mgr, err := chartmanager.NewChartManager(opts)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Chart manager ready: %d charts indexed\n", mgr.ChartCount())
}

Run it:

go run main.go

First run will download the NOAA catalog (~90MB, takes 1-2 seconds). Subsequent runs use the cached catalog.

Dependencies​

The library automatically installs these dependencies:

  • github.com/beetlebugorg/s57/pkg/s57 - S-57 ENC parser
  • github.com/beetlebugorg/iso8211/pkg/iso8211 - ISO 8211 file format parser
  • github.com/dhconnelly/rtreego - R-tree for spatial indexing

Cache Directories​

The chart manager uses XDG-compliant cache directories:

  • Catalog: ~/.cache/chartmanager/ENCProdCat_19115.xml
  • Charts: ~/.cache/chartmanager/charts/

Download Behavior​

Understanding what gets downloaded and when:

Catalog (Always Downloaded):

  • Size: ~90MB
  • When: Automatically on first use
  • Frequency: Refreshed weekly (configurable)
  • Contains: Metadata for all 6500+ charts (names, bounds, sizes)
  • Network: Uses HTTP ETag/Last-Modified for efficient updates

Charts (Downloaded On-Demand):

  • Size: Varies per chart (0.1-50MB, typically 1-5MB)
  • When: Only when you call GetChartsForViewport() or GetChart()
  • Frequency: Downloaded once, then cached
  • Contains: Actual S-57 chart data (features, geometry)

You control chart downloads:

  • Use QueryCatalog() to browse without downloading
  • Use GetChartsForViewport() when ready to download
  • Charts are cached after first download

Cache Space Requirements​

  • Catalog only: ~90MB (always downloaded)
  • Each chart: 0.1-50MB (downloaded on-demand)
  • Typical usage: 90MB catalog + 50-500MB charts (varies by region)
  • Full NOAA collection: ~30GB (6500+ charts, rarely needed)
Lazy Loading

With lazy loading, you'll only download charts you actually use. The catalog download happens automatically, but chart downloads are under your control via API method choice.

HTTP Caching​

The chart manager implements intelligent HTTP caching:

  • ETag/Last-Modified: Catalog re-downloaded only when NOAA updates it
  • 304 Not Modified: Avoids unnecessary 90MB downloads
  • Automatic: No user configuration needed

You can force a catalog refresh:

chartmanager catalog download --force

Next Steps​