Skip to main content

Crate oxigdal_shapefile

Crate oxigdal_shapefile 

Source
Expand description

OxiGDAL Shapefile Driver - ESRI Shapefile Implementation

This crate provides a pure Rust implementation of ESRI Shapefile reading and writing for the OxiGDAL ecosystem. It supports the complete Shapefile format including:

  • .shp files (geometry)
  • .dbf files (attributes)
  • .shx files (spatial index)

§Supported Geometry Types

  • Point, PointZ, PointM
  • PolyLine, PolyLineZ, PolyLineM
  • Polygon, PolygonZ, PolygonM
  • MultiPoint, MultiPointZ, MultiPointM

§Features

  • Pure Rust implementation (no C/Fortran dependencies)
  • Support for all DBF field types (Character, Number, Logical, Date, Float)
  • Proper encoding handling with code page support
  • Comprehensive error handling
  • No unwrap() or panic!() in production code
  • Round-trip compatibility (read → modify → write)
  • Spatial index (.shx) support

§Example - Reading

use oxigdal_shapefile::ShapefileReader;

// Open a Shapefile (reads .shp, .dbf, and .shx)
let reader = ShapefileReader::open("path/to/shapefile")?;

// Read all features
let features = reader.read_features()?;

for feature in &features {
    println!("Record {}: {:?}", feature.record_number, feature.geometry);
    println!("Attributes: {:?}", feature.attributes);
}

§Example - Writing

use oxigdal_shapefile::{ShapefileWriter, ShapefileSchemaBuilder};
use oxigdal_shapefile::shp::shapes::ShapeType;
use std::env;

// Create schema
let schema = ShapefileSchemaBuilder::new()
    .add_character_field("NAME", 50)?
    .add_numeric_field("VALUE", 10, 2)?
    .build();

// Create writer
let temp_dir = env::temp_dir();
let output_path = temp_dir.join("output");
let mut writer = ShapefileWriter::new(output_path, ShapeType::Point, schema)?;

// Write features (example omitted for brevity)
// writer.write_features(&features)?;

§File Format

A Shapefile consists of three required files:

  1. .shp - Main file containing geometry data
  2. .dbf - dBase file containing attribute data
  3. .shx - Index file containing record offsets

Additional optional files include .prj (projection), .cpg (code page), etc.

§Binary Format Details

§.shp File Structure

  • Header (100 bytes)
    • File code: 9994 (big endian)
    • File length in 16-bit words (big endian)
    • Version: 1000 (little endian)
    • Shape type (little endian)
    • Bounding box (8 doubles, little endian)
  • Records (variable length)
    • Record header (8 bytes, big endian)
    • Shape content (variable, little endian)

§.dbf File Structure

  • Header (32 bytes)
    • Version, date, record count, header size, record size
  • Field descriptors (32 bytes each)
  • Header terminator (0x0D)
  • Records (fixed length based on field descriptors)
  • File terminator (0x1A)

§.shx File Structure

  • Header (100 bytes, same as .shp)
  • Index entries (8 bytes each)
    • Offset (4 bytes, big endian)
    • Content length (4 bytes, big endian)

§COOLJAPAN Policies

  • Pure Rust implementation (no C/C++ dependencies)
  • No unwrap() or expect() in production code
  • Comprehensive error handling with descriptive errors
  • Extensive testing (unit + integration + property-based)
  • Clean API design following Rust idioms
  • Files under 2000 lines (use splitrs for refactoring)

§Performance Considerations

  • Buffered I/O for efficient reading/writing
  • Spatial index (.shx) for fast random access
  • Streaming API for large files (iterate records one at a time)
  • Zero-copy optimizations where possible

§Limitations

  • Currently only Point geometries are fully supported for conversion to OxiGDAL
  • PolyLine, Polygon, and MultiPoint parsing is implemented but conversion pending
  • MultiPatch (3D surfaces) support is limited
  • No support for memo fields (.dbt files)

§References

Re-exports§

pub use error::Result;
pub use error::ShapefileError;
pub use reader::ShapefileFeature;
pub use reader::ShapefileReader;
pub use writer::ShapefileSchemaBuilder;
pub use writer::ShapefileWriter;
pub use shp::shapes::MultiPartShapeM;
pub use shp::shapes::MultiPartShapeZ;
pub use shp::shapes::Point;
pub use shp::shapes::PointM;
pub use shp::shapes::PointZ;
pub use shp::shapes::ShapeType;
pub use shp::Shape;
pub use shp::ShapeRecord;
pub use dbf::FieldDescriptor;
pub use dbf::FieldType;
pub use dbf::FieldValue;

Modules§

dbf
DBF (.dbf) attribute file handling
error
Error types for Shapefile operations
reader
Shapefile reader - coordinates reading from .shp, .dbf, and .shx files
shp
Shapefile (.shp) binary geometry file handling
shx
Shapefile index (.shx) file handling
writer
Shapefile writer - coordinates writing to .shp, .dbf, and .shx files

Constants§

DBF_EXTENSION
DBF file extension
FILE_CODE
Shapefile magic number (file code)
FILE_EXTENSION
Shapefile file extension
FILE_VERSION
Shapefile version
NAME
Crate name
SHX_EXTENSION
SHX file extension
VERSION
Crate version