ne

A command-line tool for extracting vector basemap data from the Natural Earth dataset:

ne extract --scale 110 --extent -92,28,-88,32

ne wraps the GDAL ogr2ogr utility to quickly extract relevant geospatial layers from Natural Earth in shapefile format for a specific geographic extent.

Features

• Extract multiple Natural Earth layers for a specific geographic extent
• Choose from NE’s three detail levels: 1:10m, 1:50m, or 1:110m scale
• Apply buffer around your extent for context, with independent control for east-west and north-south
• Default basemap layer set or custom layer selection

Prerequisites

Before installing ne, you need:

1. Ruby 3.2 or later
2. GDAL with the ogr2ogr utility installed
   • macOS: brew install gdal
   • Check installation: ogr2ogr --version
3. Natural Earth dataset installed locally
   • Default location: /Users/Shared/Geodata/ne
   • Can be customized via the NE_DATA_DIR environment variable (see Configuration below)

Installation

Clone the repository and install as a local gem:

git clone https://github.com/anandaroop/ne.git
cd ne
bundle install
bundle exec rake install  # installs onto your system

Configuration

Custom Natural Earth Data Directory

By default, ne expects the Natural Earth dataset to be located at /Users/Shared/Geodata/ne. If your dataset is in a different location, you can configure it using the NE_DATA_DIR environment variable.

One-time usage:

NE_DATA_DIR=/path/to/your/natural-earth ne extract --scale 110 --extent -92,28,-88,32

Persistent configuration:

Add to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export NE_DATA_DIR=/path/to/your/natural-earth

Then use ne commands normally:

ne extract --scale 110 --extent -92,28,-88,32

The configured path will also be recorded in the metadata.json file of each extraction for reproducibility.

Usage

List Available Layers

View all available Natural Earth layers:

ne list

Filter by scale:

ne list --scale 110
ne list -s 50

Filter by theme:

ne list --theme physical
ne list -t cultural

Filter to only default layers (a handful of basic physical and cultural layers that ne extract will extract by default, unless an a list of layers is explicity specified; see below):

ne list --default
ne list -d

Combine filters:

ne list --scale 10 --theme cultural --default

Extract Data

Extract Natural Earth data for a specific geographic extent:

ne extract --scale 110 --extent -92,28,-88,32

Required Options

• --scale or -s: Scale of the data

  • 10 - 1:10,000,000 (largest scale, greatest detail)
  • 50 - 1:50,000,000 (intermediate scale, moderate detail)
  • 110 - 1:110,000,000 (smallest scale, least detail)

• --extent or -e: Geographic bounding box in the format xmin,ymin,xmax,ymax

  • Example: -95.0,28.0,-87.7,33.8 (Gulf Coast region)

Optional Options

• --buffer or -b: Expand the extent by a percentage (default: 20%)

  • Single value applies to both axes: --buffer 15 (15% buffer on all sides)
  • Two values for independent control: --buffer 25,15 (25% east-west, 15% north-south)
  • Specify as decimal (0-1) or percentage (1-100)
  • Examples: --buffer 0.15, --buffer 15, --buffer 25,15

• --layers or -l: Comma-separated list of layers to extract

  • Default layers (if omitted):
    • land
    • lakes
    • rivers_lake_centerlines_scale_rank
    • admin_0_countries
    • admin_0_boundary_lines_disputed_areas
    • admin_0_boundary_lines_land
    • admin_1_states_provinces_scale_rank
    • admin_1_states_provinces_lines
  • Use default to include default layers: --layers default
  • Specify custom layers: --layers land,lakes,coastline
  • Combine default + extras: --layers default,glaciated_areas,populated_places

• --output or -o: Output directory (default: current directory)

  • Absolute path: --output /path/to/output
  • Relative path: --output ../extracts
  • Home directory: --output ~/geodata

Examples

Basic extraction with defaults

Extract Gulf Coast region at 1:110m scale with default layers and 20% buffer:

ne extract --scale 110 --extent -95,28,-88,32

Custom buffer

Extract with 15% buffer:

ne extract --scale 110 --extent -92,28,-88,32 --buffer 0.15

Extract with independent east-west and north-south buffers:

ne extract --scale 110 --extent -92,28,-88,32 --buffer 25,15

Custom layers

Extract specific layers:

ne extract --scale 110 --extent -92,28,-88,32 --layers land,lakes,rivers_lake_centerlines_scale_rank,populated_places_simple

Default layers plus extras

Add glaciated areas to the default layer set:

ne extract --scale 110 --extent -92,28,-88,32 --layers default,glaciated_areas

High detail extraction

Extract at 1:10m scale for maximum detail:

ne extract --scale 10 --extent -95,28,-88,32 --buffer 25

Custom output directory

Extract to a specific directory:

ne extract --scale 110 --extent -92,28,-88,32 --output ~/geodata/extracts

Show Example Commands

Display a curated list of example usage commands:

ne examples
ne tldr

This shows common usage patterns with comments explaining each command.

Clean Up Extractions

Remove Natural Earth output directories from the current directory:

ne clean

This command:

• Scans the current directory for Natural Earth extraction folders (matching pattern ne-{scale}m-{coordinates}…)
• Shows a list of directories to be deleted
• Asks for confirmation before deletion
• Reports success or failure for each deletion

Show Version

Display the current version of the ne tool:

ne version

Output

Extracted data is saved to a directory named based on the scale and extent:

ne-110m--92-28--88-32/

If the directory already exists, a sequence number is automatically appended:

ne-110m--92-28--88-32-1/
ne-110m--92-28--88-32-2/

Each directory contains the extracted layers as shapefiles with their associated files (.shp, .dbf, .shx, .prj).

Troubleshooting

"ogr2ogr command not found"

GDAL is not installed or not in your PATH. Install GDAL using your system's package manager.

"Source file not found"

The Natural Earth dataset is not installed at the expected location, or the specific layer is not available at the requested scale.

Solutions:

• Verify the dataset exists at /Users/Shared/Geodata/ne (default location)
• If your dataset is elsewhere, set the NE_DATA_DIR environment variable (see Configuration section)
• Use ne list --scale <scale> to see available layers at the specified scale

"Output directory does not exist"

When using --output, ensure the directory exists before running the extraction. The tool will not create the parent directory, only the extraction subdirectory.

Development

See AGENTS.md for development guidelines and project structure.

Running Tests

bundle exec rake           # Run tests and linter
bundle exec rake spec      # Run tests only
bundle exec rake lint      # Run linter only
bundle exec rake fix       # Auto-fix linter issues

License

MIT