@atlas-composer/projection-loader

A simple runtime engine for composite projections.

This package allows you to render composite projections exported from Atlas Composer in your own applications. It is lightweight, and works seamlessly with D3.js.

Features

• Zero runtime dependencies (excluding your choice of projection library).
• plugin architecture: Only import the projection definitions you need.
• Type-Safe: Written in TypeScript with full type definitions.

Installation

npm install @atlas-composer/projection-loader d3-geo

Usage

import { ProjectionLoader } from '@atlas-composer/projection-loader'
import * as d3 from 'd3-geo'
import config from './my-exported-config.json'

// Create a loader instance
const loader = new ProjectionLoader()

// Register the projections required by your composite projection
loader.register('mercator', () => d3.geoMercator())
loader.register('conic-conformal', () => d3.geoConicConformal())

// Load the composite projection
const projection = loader.load(config, {
  width: 800,
  height: 600
})

// Use with D3
const path = d3.geoPath(projection)

d3.select('svg')
  .selectAll('path')
  .data(geojson.features)
  .join('path')
  .attr('d', path)

API

ProjectionLoader

• new ProjectionLoader() - Create a loader instance
• loader.register(id, factory) - Register a projection factory
• loader.registerAll(factories) - Register multiple projections from an object
• loader.load(config, options) - Load a composite projection from configuration
• loader.loadFromJSON(jsonString, options) - Load from a JSON string
• loader.isRegistered(id) - Check if a projection is registered
• loader.getRegistered() - Get all registered projection IDs
• loader.unregister(id) - Remove a registered projection
• loader.clear() - Clear all registered projections

CompositeProjectionLike

The projection returned by loader.load() supports dynamic scaling:

const projection = loader.load(config, { width: 960, height: 500 })

// Get/set scale dynamically (recalculates all sub-projections)
projection.scale() // Get current scale
projection.scale(5000) // Set new scale

// Get/set translate dynamically
projection.translate() // Get current translate [x, y]
projection.translate([480, 250]) // Set new translate

// Fit to new dimensions (compatible with Observable Plot)
projection.fitSize([800, 600], {})

// Fit to extent with margins
projection.fitExtent([[20, 20], [780, 580]], {})

// Inversion works with dynamic scaling
projection.invert([400, 300]) // Returns [lon, lat] or null

This makes the projection fully compatible with Observable Plot's auto-sizing behavior.

Acknowledgments

This package uses composite projection techniques derived from d3-geo by Mike Bostock (ISC License), with inspiration from d3-composite-projections by Roger Veciana. See NOTICES.md for details.

License

MIT © ShallowRed