🥮 mooncakes.io

    moon-shapefile

    MoonBit Shapefile geometry, index and attribute table reader/writer

    shapefile
    gis
    dbf
    geojson
    Download zip
    Author
    Version
    0.1.0
    License
    MIT
    Repository
    Last updated
    7 days ago
    Downloads
    6

    #moon-shapefile

    moon-shapefile 是使用 MoonBit 编写的 Shapefile 地理数据读写与转换库，提供 SHP 几何文件、SHX 索引文件和 DBF 属性表的联合处理能力。

    #项目能力

    • 读取和写入 Null、Point、MultiPoint、PolyLine、Polygon 及 Z/M 变体；
    • 检查文件头、记录长度、索引偏移、几何范围和属性行数量；
    • 保留 DBF 物理行顺序和删除标记，避免几何与属性错位；
    • 按边界框或属性字段筛选数据集；
    • 将点、线和多边形转换为 GeoJSON，并检查多边形环拓扑；
    • 提供统计、几何变换、最近顶点和格式化诊断接口；
    • 对截断文件、错误索引、非法坐标、字段溢出和不支持类型返回结构化错误。

    #最小示例

    let shape = {
      kind: @shapefile.Point,
      points: [@shapefile.coordinate(116.4, 39.9)],
      parts: [],
    }
    let files = @shapefile.write_shp(@shapefile.Point, [shape])
    let parsed = @shapefile.read_shp(files.shp)
    println(parsed.records.length().to_string())

    运行测试和检查：

    moon check --deny-warn
moon test --deny-warn
moon fmt --check
moon build --target wasm-gc
moon run cmd/main

    #设计边界

    首版不做坐标投影转换、MultiPatch、DBF Memo、网络或 ZIP 文件读取。.prj 文件可以随数据集保存，但不会被库自动解释。GeoJSON 导出默认要求调用者确认 坐标是经纬度；投影坐标需要显式设置 allow_projected=true。

    #许可证和来源

    本项目采用 MIT 许可证。文件布局依据公开的 ESRI Shapefile Technical Description，DBF 兼容性参考 PyShp 的公开行为，但仓库不包含 PyShp 源代码。 详细说明见 THIRD_PARTY.md 和 项目申报书。

    ShapeError

    source
    pub suberror ShapeError {
      InvalidData(Int, String)
    } derive(
    Debug    )

    Errors always identify the byte offset or logical record involved.

    Bounds

    source
    pub(all) struct Bounds {
      xmin : Double
      ymin : Double
      xmax : Double
      ymax : Double
    } derive(Eq, 
    Debug    )

    Bounds::contains

    source
    fn Bounds::contains(self : Bounds, point : Coordinate) -> Bool

    Bounds::intersection

    source
    fn Bounds::intersection(self : Bounds, other : Bounds) -> Bounds? raise ShapeError

    Intersection can be a zero-width/height rectangle when boundaries touch.

    Bounds::intersects

    source
    fn Bounds::intersects(self : Bounds, other : Bounds) -> Bool

    Bounds::union

    source
    fn Bounds::union(self : Bounds, other : Bounds) -> Bounds raise ShapeError

    Combine two valid bounding rectangles. Inputs are validated before use.

    Bounds::validate

    source
    fn Bounds::validate(self : Bounds) -> Unit raise ShapeError

    Coordinate

    source
    pub(all) struct Coordinate {
      x : Double
      y : Double
      z : Double?
      m : Double?
    } derive(Eq, 
    Debug    )

    Dataset

    source
    pub(all) struct Dataset {
      kind : ShapeType
      shapes : Array[Shape]
      table : 
    Table
      prj : String?
    } derive(
    Debug    )

    A geometry table whose rows retain the physical SHP/DBF record alignment.

    Dataset::filter_bbox

    source
    fn Dataset::filter_bbox(self : Dataset, bounds : Bounds, include_deleted? : Bool) -> Dataset raise ShapeError

    Dataset::filter_equal

    source
    fn Dataset::filter_equal(self : Dataset, field : String, value : 
    Value    , include_deleted? : Bool) -> Dataset raise ShapeError

    Dataset::project_fields

    source
    fn Dataset::project_fields(self : Dataset, names : Array[String]) -> Dataset raise ShapeError

    Dataset::select_indices

    source
    fn Dataset::select_indices(self : Dataset, indices : Array[Int]) -> Dataset raise ShapeError

    Dataset::to_geojson

    source
    fn Dataset::to_geojson(self : Dataset, allow_projected? : Bool, include_deleted? : Bool) -> Json raise ShapeError

    Dataset::validate

    source
    fn Dataset::validate(self : Dataset) -> Unit raise ShapeError

    Dataset::write_dataset

    source

    DatasetFiles

    source
    pub(all) struct DatasetFiles {
      shp : Bytes
      shx : Bytes
      dbf : Bytes
      prj : String?
    } derive(
    Debug    )

    pub(all) struct Header {
      file_length : Int
      kind : ShapeType
      bounds : Bounds
      zmin : Double
      zmax : Double
      mmin : Double
      mmax : Double
    } derive(
    Debug    )

    Parsed file header; ranges remain available for inspection.

    IndexEntry

    source
    pub(all) struct IndexEntry {
      offset : Int
      content_length : Int
    } derive(Eq, 
    Debug    )

    IndexedReader

    source
    pub struct IndexedReader {
      data : Bytes
      file_header : Header
      entries : Array[IndexEntry]
      limits : ReadLimits
    }

    Random access validates file/index structure up front and geometry on access.

    IndexedReader::entry

    source
    fn IndexedReader::entry(self : IndexedReader, index : Int) -> IndexEntry raise ShapeError

    IndexedReader::header

    source
    fn IndexedReader::header(self : IndexedReader) -> Header

    IndexedReader::open

    source
    fn IndexedReader::open(shp : Bytes, shx : Bytes, limits? : ReadLimits) -> IndexedReader raise ShapeError

    IndexedReader::record_at

    source
    fn IndexedReader::record_at(self : IndexedReader, index : Int) -> Record raise ShapeError

    IndexedReader::record_count

    source
    fn IndexedReader::record_count(self : IndexedReader) -> Int

    IndexedReader::select

    source
    fn IndexedReader::select(self : IndexedReader, indices : Array[Int]) -> Array[Record] raise ShapeError

    Only selected records are decoded; order and duplicate indices are preserved.

    ReadLimits

    source
    pub(all) struct ReadLimits {
      max_records : Int
      max_points_per_record : Int
      max_parts_per_record : Int
      max_file_bytes : Int
    } derive(
    Debug    )

    Resource limits apply before allocating point or record arrays.

    ReadLimits::default

    source
    fn ReadLimits::default() -> ReadLimits

    Record

    source
    pub(all) struct Record {
      number : Int
      offset : Int
      content_length : Int
      shape : Shape
    } derive(
    Debug    )

    Shape

    source
    pub(all) struct Shape {
      kind : ShapeType
      points : Array[Coordinate]
      parts : Array[Int]
    } derive(Eq, 
    Debug    )

    Shape::bounds

    source
    fn Shape::bounds(self : Shape) -> Bounds?

    Shape::contains_point

    source
    fn Shape::contains_point(self : Shape, point : Coordinate) -> Bool raise ShapeError

    Inclusive planar membership. Polygon boundaries (including hole boundaries) count as contained. Z and M are ignored; exact XY comparisons are used.

    Shape::intersects_bounds

    source
    fn Shape::intersects_bounds(self : Shape, bounds : Bounds) -> Bool raise ShapeError

    True geometric intersection with a closed XY rectangle, including touches. Unlike a bounding-box prefilter, this respects concavities and polygon holes.

    Shape::planar_area

    source
    fn Shape::planar_area(self : Shape) -> Double raise ShapeError

    Area in squared input XY units after topology validation. Winding has no effect; holes subtract and islands add. Non-polygons return zero.

    Shape::planar_length

    source
    fn Shape::planar_length(self : Shape) -> Double raise ShapeError

    Euclidean length in input XY units. Polygon results include hole boundaries; point geometries have zero length. No geodesic interpretation is implied.

    Shape::to_geojson

    source
    fn Shape::to_geojson(self : Shape, allow_projected? : Bool) -> Json raise ShapeError

    Export a geometry object. Input is longitude/latitude by default; the opt-in permits projected output without claiming RFC 7946 coordinate compliance. M is omitted, and Z is retained. Polygon rings may arrive in any order or winding; nesting determines shell/hole roles, including islands in holes.

    Shape::validate

    source
    fn Shape::validate(self : Shape) -> Unit raise ShapeError

    ShapeFiles

    source
    pub(all) struct ShapeFiles {
      shp : Bytes
      shx : Bytes
    } derive(
    Debug    )

    Matching SHP and SHX byte streams, ready for filesystem or network storage.

    ShapeStats

    source
    pub(all) struct ShapeStats {
      record_count : Int
      point_count : Int
      part_count : Int
      null_count : Int
      bounds : Bounds?
      total_length : Double
      total_area : Double
    } derive(
    Debug    )

    Summary statistics useful to import pipelines and CLI reports.

    ShapeType

    source
    pub(all) enum ShapeType {
      Null
      Point
      PolyLine
      Polygon
      MultiPoint
      PointZ
      PolyLineZ
      PolygonZ
      MultiPointZ
      PointM
      PolyLineM
      PolygonM
      MultiPointM
    } derive(Eq, 
    Debug    )

    ESRI shape codes. MultiPatch is deliberately unsupported.

    ShapeType::code

    source
    fn ShapeType::code(self : ShapeType) -> Int

    ShapeType::has_m

    source
    fn ShapeType::has_m(self : ShapeType) -> Bool

    ShapeType::has_z

    source
    fn ShapeType::has_z(self : ShapeType) -> Bool

    ShapeType::is_line

    source
    fn ShapeType::is_line(self : ShapeType) -> Bool

    ShapeType::is_multi

    source
    fn ShapeType::is_multi(self : ShapeType) -> Bool

    ShapeType::is_point

    source
    fn ShapeType::is_point(self : ShapeType) -> Bool

    ShapeType::is_polygon

    source
    fn ShapeType::is_polygon(self : ShapeType) -> Bool

    Shapefile

    source
    pub(all) struct Shapefile {
      kind : ShapeType
      records : Array[Record]
      bounds : Bounds?
    } derive(
    Debug    )

    ShpReader

    source
    pub struct ShpReader {
      data : Bytes
      header : Header
      limits : ReadLimits
      position : Int
      count : Int
    }

    Cursor holds original bytes and decodes one record at a time.

    ShpReader::header

    source
    fn ShpReader::header(self : ShpReader) -> Header

    ShpReader::next

    source
    fn ShpReader::next(self : ShpReader) -> Record? raise ShapeError

    A failed decode does not advance the cursor.

    ShpReader::open

    source
    fn ShpReader::open(data : Bytes, limits? : ReadLimits) -> ShpReader raise ShapeError

    ShpReader::position

    source
    fn ShpReader::position(self : ShpReader) -> Int

    ShpWriter

    source
    pub struct ShpWriter {
      kind : ShapeType
      limits : ReadLimits
      records : Array[Bytes]
      total_bytes : Int
      bounds : Bounds?
      zrange : (Double, Double)?
      mrange : (Double, Double)?
    }

    Accumulates encoded records; append validates a record before mutation.

    ShpWriter::append

    source
    fn ShpWriter::append(self : ShpWriter, shape : Shape) -> Unit raise ShapeError

    ShpWriter::finish

    source
    fn ShpWriter::finish(self : ShpWriter) -> ShapeFiles

    Finishing is repeatable and does not consume the writer.

    ShpWriter::new

    source
    fn ShpWriter::new(kind : ShapeType, limits? : ReadLimits) -> ShpWriter raise ShapeError

    ShpWriter::record_count

    source
    fn ShpWriter::record_count(self : ShpWriter) -> Int

    bounds_of

    source
    fn bounds_of(shapes : Array[Shape]) -> Bounds? raise ShapeError

    bounds_to_text

    source
    fn bounds_to_text(bounds : Bounds?) -> String

    centroid

    source
    fn centroid(shape : Shape) -> Coordinate? raise ShapeError

    clamp_bounds

    source
    fn clamp_bounds(shape : Shape, bounds : Bounds) -> Shape raise ShapeError

    coordinate

    source
    fn coordinate(x : Double, y : Double, z? : Double, m? : Double) -> Coordinate

    count_parts

    source
    fn count_parts(shapes : Array[Shape]) -> Int raise ShapeError

    count_vertices

    source
    fn count_vertices(shapes : Array[Shape]) -> Int raise ShapeError

    intersecting_indices

    source
    fn intersecting_indices(shapes : Array[Shape], query : Bounds) -> Array[Int] raise ShapeError

    Returns physical record indices whose bounding boxes overlap the query.

    locate_point

    source
    fn locate_point(shapes : Array[Shape], point : Coordinate) -> Int? raise ShapeError

    Return the first record that contains a point under inclusive XY semantics.

    m_coverage

    source
    fn m_coverage(shapes : Array[Shape]) -> Double raise ShapeError

    Calculate the fraction of points that carry an M ordinate.

    nearest_vertex

    source
    fn nearest_vertex(shape : Shape, target : Coordinate) -> (Int, Double)? raise ShapeError

    read_dataset

    source
    fn read_dataset(shp : Bytes, shx : Bytes, dbf : Bytes, encoding? : 
    Encoding    , prj? : String?) -> Dataset raise ShapeError

    read_header

    source
    fn read_header(data : Bytes) -> Header raise ShapeError

    Read and verify the 100-byte header. Full file bytes are required.

    read_index

    source
    fn read_index(data : Bytes, limits? : ReadLimits) -> Array[IndexEntry] raise ShapeError

    Decode SHX entries, checking contiguous byte boundaries from offset 100.

    read_shp

    source
    fn read_shp(data : Bytes, limits? : ReadLimits) -> Shapefile raise ShapeError

    rebuild_index

    source
    fn rebuild_index(shp : Bytes, limits? : ReadLimits) -> Bytes raise ShapeError

    Rebuild a missing index from a validated SHP stream.

    reverse_parts

    source
    fn reverse_parts(shape : Shape) -> Shape raise ShapeError

    scale_shape

    source
    fn scale_shape(shape : Shape, sx : Double, sy : Double) -> Shape raise ShapeError

    shape_from_geojson

    source
    fn shape_from_geojson(value : Json, kind : ShapeType) -> Shape raise ShapeError

    Import a GeoJSON geometry into an explicit ESRI shape type. Two ordinates are required for XY/M types, three for Z types. Measures remain absent. Feature wrappers and collections must be handled by the dataset layer. Coordinates are preserved without reprojection or longitude wrapping.

    shape_type

    source
    fn shape_type(code : Int) -> ShapeType raise ShapeError

    shape_type_name

    source
    fn shape_type_name(kind : ShapeType) -> String

    Human-readable summaries for command-line adapters.

    stable_select

    source
    fn stable_select(shapes : Array[Shape], indices : Array[Int]) -> Array[Shape] raise ShapeError

    Stable filter preserving original record order and duplicate indices.

    stats_to_text

    source
    fn stats_to_text(stats : ShapeStats) -> String

    summarize

    source
    fn summarize(shapes : Array[Shape]) -> ShapeStats raise ShapeError

    translate_shape

    source
    fn translate_shape(shape : Shape, dx : Double, dy : Double) -> Shape raise ShapeError

    Small, allocation-conscious geometry operations used by importers.

    type_histogram

    source
    fn type_histogram(shapes : Array[Shape]) -> Map[Int, Int] raise ShapeError

    Compute a histogram of records by ShapeType numeric code.

    validate_bounds

    source
    fn validate_bounds(shapes : Array[Shape], declared : Bounds) -> Unit raise ShapeError

    Check that all bounds are finite and mutually compatible with their shapes.

    validate_filename_prefix

    source
    fn validate_filename_prefix(prefix : String) -> Unit raise ShapeError

    validate_shape_family

    source
    fn validate_shape_family(kind : ShapeType, shapes : Array[Shape]) -> Unit raise ShapeError

    Validate that a collection has one file-compatible shape family.

    validate_shx

    source
    fn validate_shx(shp : Bytes, shx : Bytes, limits? : ReadLimits) -> Unit raise ShapeError

    Fully verifies the SHX table against decoded SHP records.

    write_shp

    source
    fn write_shp(kind : ShapeType, shapes : Array[Shape], limits? : ReadLimits) -> ShapeFiles raise ShapeError

    z_coverage

    source
    fn z_coverage(shapes : Array[Shape]) -> Double raise ShapeError

    Calculate the fraction of points that carry a Z ordinate.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io