cad2geo

Pure-Python Netcad NCZ/NCA CAD Inspection and High-Performance GeoJSON Conversion Engine.

📖 Open Interactive Web Manual (GitHub Pages) • 📦 PyPI Package • 🐛 Issue Tracker

🌟 Overview

cad2geo is a lightweight, zero-dependency Python library for inspecting Netcad NCZ (compressed archive) and NCA (raw binary CAD drawing stream) files and converting CAD geometries into OGC-compliant GeoJSON datasets.

Extracted from the high-value headless core of the 02CadGis and PlanX geospatial ecosystem, cad2geo operates 100% headless using only Python's standard library (struct, zlib, dataclasses, json). It requires zero proprietary CAD installations, zero QGIS runtimes, and zero GDAL C-extensions.

🔬 Key Capabilities

1. Pure-Python NCZ/NCA Binary Block Scanner:
   • Directly decompresses zlib archive containers and parses binary stream records for Points, Lines, Polylines, Arcs, Circles, Text annotations, and Polygons.
2. $\mathcal{O}(1)$ Fast Layer Catalog Inspection:
   • Scans file headers in under 5 milliseconds, extracting layer codes, layer names, line types, display colors, and record counts without decompressing coordinates.
3. Selective Layer Decoding & Memory Optimization:
   • Skips unneeded byte blocks in the binary stream when decoding specific layers (e.g. layers=[1, 3, 7]), saving up to 90% RAM on massive municipal zoning plans (100MB+ NCZ files).
4. Mathematical Curve & Arc Discretization:
   • Converts circular arcs and curves into piecewise linear GIS LineStrings using exact sagitta chord tolerance ($\delta$) calculations.
5. Cadastral & Zoning Attribute Preservation:
   • Captures parcel IDs (Ada / Parsel), zoning parameters (KAKS, TAKS, Yençok), layer styles, text labels, and geometric perimeters.
6. Standard GeoJSON FeatureCollection Serialization:
   • Generates clean, standards-compliant GeoJSON with CRS headers and styling properties for immediate GIS web mapping.

📦 Installation

pip install cad2geo

🚀 Quickstart & Python API

1. Fast Layer Catalog Inspection

Inspect drawing layers and entity counts in milliseconds without loading full geometry:

from cad2geo import inspect_source

layers = inspect_source("imar_plani.ncz")

for layer in layers:
    print(f"Layer #{layer.layer_code:02d}: {layer.layer_name:<25} | Entities: {layer.record_count}")

2. Selective Decoding & GeoJSON Export

Decode only specific zoning boundaries and save directly as GeoJSON:

from cad2geo import parse_netcad, write_geojson

# Decode only layers 1, 3, and 7
result = parse_netcad("imar_plani.ncz", target_layers=[1, 3, 7])
print(f"Successfully decoded {len(result.entities)} entities across {len(result.layers)} layers.")

# Export to OGC GeoJSON FeatureCollection
write_geojson(result.entities, "zoning_boundaries.geojson")

3. In-Memory Parsing & Custom Processing

Integrate into FastAPI endpoints, AWS Lambda, or Jupyter Notebooks:

from cad2geo import parse_bytes, entities_to_feature_collection

with open("parcels.ncz", "rb") as f:
    raw_bytes = f.read()

result = parse_bytes(raw_bytes)
geojson_dict = entities_to_feature_collection(result.entities)

print(f"Features in GeoJSON: {len(geojson_dict['features'])}")

💻 Command Line Interface (CLI)

cad2geo comes with a high-performance CLI utility:

# 1. Quick inspection of NCZ layer definitions
cad2geo inspect imar_plani.ncz

# 2. Output layer metadata as machine-readable JSON
cad2geo inspect imar_plani.ncz --json

# 3. Convert full drawing to GeoJSON
cad2geo convert imar_plani.ncz master_plan.geojson

# 4. Selective layer extraction with pretty-printed JSON formatting
cad2geo convert imar_plani.ncz road_centerlines.geojson --layers 2,5 --pretty

📊 Netcad Entity Mapping Matrix

⚡ Performance Benchmarks

Benchmarked on complex municipal zoning drawings (100MB+ NCZ archives):

🧪 Development & Testing

# Clone the repository
git clone https://github.com/YusufEminoglu/cad2geo.git
cd cad2geo

# Install in editable mode with development dependencies
pip install -e ".[dev]"

# Run test suite
pytest tests/ -v --cov=cad2geo

# Run linter and type checks
ruff check .
mypy src

📄 Academic Citation

If you use cad2geo in scientific research, GIS data engineering pipelines, or academic publications, please cite:

@software{eminoglu2026cad2geo,
  author    = {Emino{\u{g}}lu, Yusuf},
  title     = {{cad2geo: Pure-Python Netcad NCZ/NCA CAD Parser and High-Performance GeoJSON Engine}},
  year      = {2026},
  publisher = {PyPI - Python Package Index},
  version   = {0.1.0},
  url       = {https://github.com/YusufEminoglu/cad2geo}
}

📜 License & Lineage

Distributed under the GPL-2.0-or-later license. The NCZ decoding lineage and third-party notices are documented in THIRD_PARTY_NOTICES.md.