NCZ2Geo

Read Netcad NCZ/NCA files in pure Python and convert them to GeoJSON, GeoPackage, Shapefile, FlatGeobuf, GeoParquet, DXF and KML/KMZ, with PlanGML / e-Plan layer classification and correct CRS metadata.

📖 Open Interactive Web Manual • 📦 PyPI Package • 🐙 GitHub • 🐛 Issue Tracker

📦 Installation

pip install NCZ2Geo

Requires Python 3.9 or newer. The only runtime dependency is turkgrid (pure-Python coordinate maths, no dependencies of its own, same author). Development tooling: pip install -e ".[dev]" (see Development Install below).

⚡ Quickstart

from ncz2geo import (
    export_entities_to_flatgeobuf, export_entities_to_geopackage, export_entities_to_geoparquet,
    export_entities_to_shapefile, export_to_kml_kmz, parse_netcad, write_geojson,
)

result = parse_netcad("plan.ncz")              # no Netcad installation needed
srid = 5254                                    # TUREF / TM30; the drawing stores it in result.epsg
print(len(result.entities), "entities,", result.epsg, "layers", result.layer_names)

write_geojson(result.entities, "plan.geojson")                       # + PlanGML / e-Plan attributes
export_entities_to_geopackage(result.entities, "plan.gpkg", srs_id=srid)
shp = export_entities_to_shapefile(result.entities, "plan.shp", srid=srid)
export_entities_to_flatgeobuf(result.entities, "plan.fgb", srid=srid)
export_entities_to_geoparquet(result.entities, "plan.parquet", srid=srid)
export_to_kml_kmz(result.entities, srid=srid).save_kmz("plan.kmz")  # converted to WGS 84
print(shp.feature_counts)

# 15 entities, EPSG:5254 layers ['ROADS', 'PARCELS', 'TEXT', 'TRIANGLES', 'MISC']
# {'Point': 8, 'LineString': 3, 'Polygon': 4}   (plan_points/_lines/_polygons.shp)

Same from the shell — the output extension picks the format and the CRS is read from the drawing:

ncz2geo convert plan.ncz plan.shp      # also .geojson .gpkg .fgb .parquet .dxf .kml .kmz

🇹🇷 Türkçe Özet

NCZ2Geo, Netcad .ncz / .nca imar planı çizimlerini saf Python ile okur ve GeoJSON, GeoPackage, Shapefile, FlatGeobuf, GeoParquet, DXF ve KML/KMZ formatlarına dönüştürür. Netcad, GDAL veya QGIS kurulumu gerekmez. Koordinat sistemi (TUREF/ITRF96 ve ED50 TM dilimleri, UTM) dosyalara doğru yazılır; KML çıktısı WGS 84'e dönüştürülür. Komut satırından: ncz2geo convert plan.ncz plan.shp. Katman adlarını PlanGML / MPYY tabakalarıyla eşleştirir, e-Plan renklerini ekler ve planın mevzuata uygunluğunu raporlayabilir. Eski ED50 planlarını TUREF/ITRF96'ya veya bir TM diliminden komşu dilime PROJ/GDAL olmadan taşır: ncz2geo convert eski_plan.ncz yeni.gpkg --srid 2320 --to-srid 5254.

pip install NCZ2Geo

Ayrıntılı kullanım kılavuzu: geophilo.com/NCZ2Geo

🌟 Overview

NCZ2Geo is a specialized Python SDK engineered specifically for Turkish urban planning workflows. It reads Netcad NCZ (compressed archive) and NCA (raw binary CAD stream) drawings, automatically resolves layer semantics against official PlanGML / MPYY (Mekânsal Planlar Yapım Yönetmeliği) schemas, and attaches official e-Plan symbology metadata to the emitted GeoJSON features.

Built entirely on the high-speed NCZ Engine v2 core, NCZ2Geo operates 100% headless in pure Python; its one dependency, turkgrid, is pure Python too.

✨ Features

• Pure Python — installs and runs on Python 3.9+; the only runtime dependency is the pure-Python coordinate library turkgrid.
• NCZ/NCA reading — bounds-checked binary block scanner, two-phase NczCatalog indexer, and selective layer decoding.
• PlanGML / MPYY identity resolution — maps Netcad layer names to official tabaka names, upper groups, function codes, and geometry types for UIP, NIP, and CDP plans.
• Official e-Plan symbology — injects standardized fill colors, opacity, labels, rules, and hatch metadata into every feature.
• PlanGML-aware GeoJSON — exports FeatureCollection documents enriched with PlanGML and e-Plan properties.
• Compliance validation — checks classification coverage, mandatory layers, geometry integrity, and produces JSON/Markdown reports.
• Plan comparison — detects added, removed, reclassified, and modified zoning features between two plan versions.
• Multi-format exporters — GeoPackage 1.2 (with R-tree spatial index), ESRI Shapefile, FlatGeobuf (with packed Hilbert R-tree index), GeoParquet 1.1, DXF R12 and KML/KMZ, all in pure Python and checked against GDAL/OGR, plus PlanGML GML, CityGML LoD, zipped GeoJSON (GeoZip) and NCZ2Geo's own compact GeoBuff format.
• CRS metadata built in — complete definitions for TUREF and ED50 3° TM zones, UTM 35N–38N, WGS 84 and Web Mercator (supported_epsg_codes()); KML output is reprojected to WGS 84 (agrees with PROJ to under a millimetre in Turkey).
• Cadastral analysis tools — zoning capacity (TAKS/KAKS), boundary simplification, parcel subdivision, easements, boundary disputes, strata titles, land consolidation, and R-Tree index planning.
• Privacy tooling — KVKK/GDPR-aware pseudonymization of cadastral attribute tables.
• Coordinate transformations — ED50 ↔ TUREF and zone-to-zone grid reprojection (reproject_entities, ncz2geo convert --to-srid), Helmert 7-parameter shifts of geocentric coordinates and 2D affine transforms.
• Fingerprinted index cache — reopening an unchanged drawing returns its layer catalog instantly.
• CLI — inspect, convert, validate, and style subcommands for automation and CI pipelines.

🧰 Development Install & Troubleshooting

Development install

Clone the repository and install the package in editable mode together with the dev extra (pytest, pytest-cov, ruff, mypy, build, and twine):

git clone https://github.com/YusufEminoglu/NCZ2Geo.git
cd NCZ2Geo
python -m pip install -e ".[dev]"

Verify the installation

python -c "import ncz2geo; print(ncz2geo.__version__)"
ncz2geo --version

Compatibility matrix

Troubleshooting

🚀 Python API Examples

1. Automatic Layer Classification

Classify layer names into official PlanGML function codes and e-Plan colors:

from ncz2geo import classify_layer

# Classify a layer name under the UIP (1/1.000) standard
classification = classify_layer("PL_GELISME_KONUT", plan_type="UIP")

print("PlanGML Function:", classification.identity.fonksiyon_adi)   # Gelişme Konut Alanı
print("PlanGML Code:", classification.identity.fonksiyon_kodu)       # 112001
print("Upper Group:", classification.identity.ust_grup_adi)          # KONUT ALANLARI / YERLEŞİM ALANLARI
print("e-Plan Fill Color:", classification.style["fill"])            # #FFFA26
print("e-Plan Opacity:", classification.style["fill_opacity"])       # 1.0
print("Matched:", classification.matched)                            # True

2. Parse a Netcad NCZ and Export Styled GeoJSON

from ncz2geo import parse_netcad, write_geojson

# 1. Parse the drawing using NCZ Engine v2
result = parse_netcad("imar_plani.ncz")
print(f"Decoded {len(result.entities)} entities across {len(result.layer_names)} layers.")
print(f"Backend: {result.parser_backend}, EPSG: {result.epsg}")

# 2. Export GeoJSON enriched with PlanGML and e-Plan attributes
collection = write_geojson(result.entities, "imar_plani_styled.geojson", plan_type="UIP")
print(f"Wrote {len(collection['features'])} feature(s).")

3. Inspect Layers Without Full Decoding

from ncz2geo import NetcadReader

reader = NetcadReader("imar_plani.ncz").index()

print(f"Backend: {reader.backend}, cached: {reader.from_cache}")
print(f"Version: {reader.version_name}, EPSG: {reader.epsg}")

for summary in reader.layer_summaries():
    print(summary.layer_code, summary.layer_name, summary.record_count, sorted(summary.families))

4. Selective Layer Extraction

Decode only the layers you need, keeping memory use low on large drawings:

from ncz2geo import NetcadReader, write_geojson

reader = NetcadReader("imar_plani.ncz").index()

# Decode only residential and green-space layers (e.g. layer codes 1 and 4)
entities = reader.decode_layers([1, 4])
write_geojson(entities, "konut_ve_parklar.geojson", plan_type="UIP")

5. Validate PlanGML and e-Plan Compliance

from ncz2geo import validate_plan

report = validate_plan("imar_plani.ncz", plan_type="UIP")

print(f"Valid: {report.is_valid}")
print(f"Quality score: {report.quality_score:.1f}/100")
print(f"Classified layers: {report.matched_layers}/{report.total_layers}")

# Markdown and JSON renderings are available for reports and CI output
payload = report.to_dict()
markdown_report = report.to_markdown()  # GitHub-flavored Markdown string

6. Analyze Zoning Capacity and Export to a GeoPackage

from ncz2geo import (
    calculate_zoning_capacity,
    export_entities_to_geopackage,
    parse_netcad,
)

result = parse_netcad("imar_plani.ncz")

capacity = calculate_zoning_capacity(result.entities, plan_type="UIP")
print(f"Residents: {capacity.total_estimated_residents}")
print(f"Construction area: {capacity.total_construction_area_m2:.1f} m²")
print(f"Parking spaces: {capacity.total_required_parking_spaces}")

export_entities_to_geopackage(result.entities, "imar_plani.gpkg")

7. Export 3D KML / KMZ

from ncz2geo import export_to_kml_kmz, parse_netcad

result = parse_netcad("kadastro.ncz")
# KML is always WGS 84: pass the drawing's EPSG code (here TUREF / TM30) to reproject.
kml_result = export_to_kml_kmz(result.entities, document_name="Kadastro Planı", srid=5254)

kml_result.save_kml("kadastro.kml")
kml_result.save_kmz("kadastro.kmz")

7b. Reproject ED50 Plans to TUREF (or Between TM Zones)

Many older plans are drawn on ED50 3° TM grids, while today's cadastre and e-Plan submissions use TUREF (ITRF96). reproject_entities converts every vertex through geographic coordinates — inverse projection, the ED50 → WGS 84 Helmert shift PROJ uses for Turkey, forward projection — with no PROJ or GDAL install, using turkgrid for the coordinate maths. The projections agree with PROJ to the nanometre; the ED50 datum shift itself is good to about a metre, the usual accuracy of a parameter-only ED50 conversion without local control points.

from ncz2geo import parse_netcad, reproject_coordinate, reproject_entities, write_geojson

print(reproject_coordinate(500000.0, 4200000.0, 2320, 5254))  # ED50/TM30 -> TUREF/TM30
# (499965.318..., 4199815.642...)

plan = parse_netcad("eski_plan_ed50.ncz")
turef = reproject_entities(plan.entities, source_srid=2320, target_srid=5254)
write_geojson(turef, "plan_turef.geojson", srid=5254)

# A plan that crosses into the neighbouring zone: TUREF/TM30 -> TUREF/TM33
tm33 = reproject_entities(turef, 5254, 5255)

Heights are kept unchanged. Any pair of bundled codes works (TUREF and ED50 TM27–TM45, UTM 35N–38N, WGS 84, Web Mercator); supported_epsg_codes() lists them.

8. Compare Two Plan Versions

from ncz2geo import compare_plans

diff = compare_plans("plan_2025.ncz", "plan_2026.ncz", plan_type="UIP")

print(f"Added: {diff.added_features_count}")
print(f"Removed: {diff.removed_features_count}")
print(f"Reclassified: {diff.reclassified_features_count}")
print(diff.to_dict())

💻 Command Line Interface (CLI)

# 1. Inspect a Netcad drawing and list PlanGML-matched layers
ncz2geo inspect imar_plani.ncz --plan-type UIP

# 2. Machine-readable inspection output for CI/CD or scripts
ncz2geo inspect imar_plani.ncz --plan-type UIP --json

# 3. Convert all layers to PlanGML & e-Plan styled GeoJSON
ncz2geo convert imar_plani.ncz imar_plani.geojson --plan-type UIP

# 4. Convert specific layer codes only
ncz2geo convert imar_plani.ncz konut_alanlari.geojson --layers 1,4,7 --plan-type UIP

# 4b. Other formats: the output extension picks the writer; --srid overrides the drawing's EPSG
ncz2geo convert imar_plani.ncz imar_plani.gpkg
ncz2geo convert imar_plani.ncz imar_plani.shp      # imar_plani_points/_lines/_polygons.shp
ncz2geo convert imar_plani.ncz imar_plani.kmz --srid 5254

# 4c. Reproject while converting: an ED50 / TM30 plan written as TUREF / TM30
ncz2geo convert eski_plan.ncz plan_turef.gpkg --srid 2320 --to-srid 5254

# 5. Validate a plan and emit a machine-readable compliance report
ncz2geo validate imar_plani.ncz --plan-type UIP --json

# Markdown reports are also available via --markdown (UTF-8 terminal recommended)
ncz2geo validate imar_plani.ncz --plan-type UIP --markdown

# 6. Generate OGC SLD, QGIS QML, and Mapbox GL style documents
ncz2geo style imar_plani.ncz --format all --out-dir styles --plan-type UIP

📋 Emitted GeoJSON Schema Properties

Every exported GeoJSON feature includes standard Netcad CAD attributes plus enriched PlanGML / e-Plan metadata:

{
  "type": "Feature",
  "geometry": { "type": "Polygon", "coordinates": [[[500000.0, 4500000.0, 0.0], ["..."]]] },
  "properties": {
    "geometry_kind": "Polygon",
    "layer_code": 0,
    "layer_name": "PL_GELISME_KONUT",
    "color_argb": 4294901760,
    "name": "",
    "label_text": "PL",
    "is_closed": true,
    "plangml_plan_type": "UIP",
    "plangml_matched": true,
    "plangml_tabaka": "PL_GELISME_KONUT",
    "plangml_ust_grup_id": "112000",
    "plangml_ust_grup_adi": "KONUT ALANLARI / YERLEŞİM ALANLARI",
    "plangml_fonksiyon_kodu": "112001",
    "plangml_fonksiyon_adi": "GELİŞME KONUT ALANI",
    "plangml_geometri": "POLYGON",
    "plangml_match_type": "exact",
    "eplan_style_key": "GELISME_KONUT",
    "eplan_style_plan_type": "UIP",
    "eplan_fill": "#FFFA26",
    "eplan_fill_opacity": 1.0,
    "eplan_label": "Gelişme Konut Alanı",
    "eplan_rule": "GELISME_KONUT",
    "eplan_style": "UIP_KONUT",
    "eplan_ust_grup": "KONUT ALANLARI"
  }
}

Unmatched layers still export with plangml_matched: false and empty classification fields, so downstream pipelines can detect them.

📚 Public API Reference

The package exports the following public names from ncz2geo. ncz2geo.__version__ reports the installed version.

Reading and inspection

Layer classification and styling

GeoJSON and GML export

Binary and cloud-native exporters

Validation, comparison, and privacy

Cadastral analysis and geometry tools

Coordinate transformations

Data model

⚡ Performance Benchmarks

🧪 Development & Testing

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

# Install in editable mode with the dev extra
pip install -e ".[dev]"

# Run the test suite with coverage
pytest tests/ -v --cov=ncz2geo

# Run the linter and type checks
ruff format src tests
ruff check .
mypy src

The dev extra installs pytest, pytest-cov, ruff, mypy, build, and twine.

📄 Academic Citation

If you use NCZ2Geo in urban planning studies, cadastral automation pipelines, or scientific research, please cite:

@software{eminoglu2026ncz2geo,
  author    = {Emino{\u{g}}lu, Yusuf},
  title     = {{NCZ2Geo: Pure-Python Netcad NCZ/NCA Reader with PlanGML Identity and e-Plan Symbology Metadata}},
  year      = {2026},
  publisher = {Zenodo},
  version   = {0.15.0},
  doi       = {10.5281/zenodo.23677241},
  url       = {https://github.com/YusufEminoglu/NCZ2Geo}
}

📜 License

Distributed under the GPL-2.0-or-later license.