Metadata-Version: 2.4
Name: ezdgn
Version: 0.1.2
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: matplotlib>=3.8 ; extra == 'dev'
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Requires-Dist: matplotlib>=3.8 ; extra == 'plot'
Provides-Extra: dev
Provides-Extra: plot
License-File: LICENSE
Summary: Native V7 DGN reader and writer for Python powered by Rust
Keywords: dgn,cad,microstation,parser,rust
Author-email: neka-nat <nekanat.stock@gmail.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/monozukuri-ai/ezdgn
Project-URL: Issues, https://github.com/monozukuri-ai/ezdgn/issues
Project-URL: Repository, https://github.com/monozukuri-ai/ezdgn

# ezdgn

`ezdgn` is a native V7 DGN reader and writer for Python,
implemented with a pure Rust core and PyO3 bindings.

## Installation

`ezdgn` requires Python 3.10 or newer.

```bash
python -m pip install ezdgn
```

Install the optional Matplotlib renderer when preview images are needed:

```bash
python -m pip install "ezdgn[plot]"
```

Building from source requires Rust 1.83 or newer. The extension uses Python's
stable ABI (`abi3`) with a Python 3.10 minimum.

## Supported scope

| Format and operation | Support |
| --- | --- |
| V7/ISFF 2D read | Native entities, hierarchy, metadata, linkages, and raw records |
| V7/ISFF 2D write | Standalone or custom-seed creation of common primitives |
| V7/ISFF 3D | Signature, raw record, and common-header inspection only |
| V8 DGN | CFB container identification and directory inspection only |

The V7 reader decodes line, line string, shape, curve, ellipse, arc, text,
cell, text node, complex chain/shape, and B-spline records as native entities.
It restores parent/child relationships without flattening component records,
decodes typed attribute linkages while retaining their exact bytes, applies
high-precision sub-UOR coordinate corrections alongside the stored integers,
and resolves outline/fill colors through the active color table. Every record,
including unsupported control and application elements, retains its original
bytes.

The writer creates standalone V7 2D files from a bundled empty seed. A custom
seed can be supplied to preserve its units, origin, and design plane. It writes
line, line string, shape, curve, ellipse, arc, circle-as-ellipse, and raw-byte
text entities with basic symbology and shape fill linkage. Coordinates outside
the selected seed's design plane are rejected instead of silently clipped.

V8 entity semantics and V7 3D geometry are not supported. The writer does not
yet create cells, complex elements, B-splines, arbitrary linkages, or perform
in-place editing. The raw V7 record framing is shared by 2D and 3D files, so
`scan_records()` can inspect a 3D stream safely without implying 3D entity
support.

## 2D entity API

```python
import ezdgn

drawing = ezdgn.readfile("drawing.dgn")

# All records remain ordered and lossless. entities contains only top-level
# graphics; all_entities also includes drawable component records.
print(len(drawing.elements), len(drawing.entities), len(drawing.all_entities))

for entity in drawing:
    print(entity.dxftype(), entity.level, entity.style)

for line in drawing.query("LINE"):
    print(line.start_uor, line.end_uor)
    print(line.start_master, line.end_master)

for text in drawing.query("TEXT"):
    print(text.text_bytes)
    print(text.decode_text())  # ASCII with strict errors by default
    print(text.decode_text("cp932", errors="replace"))

for cell in drawing.query("CELL"):
    print(cell.name, cell.origin_master, cell.transform)
    for component in drawing.children(cell):
        print("  ", component.dxftype())

for element in drawing.elements:
    for linkage in element.linkages:
        print(linkage.kind, linkage.linkage_type_name, linkage.raw_bytes)
```

`drawing.entities` contains supported top-level drawable entities only.
`drawing.all_entities` is a flat tuple in original `drawing.elements` order:
it includes both `Cell`/`ComplexChain`/`ComplexShape` container headers and
their supported drawable descendants at every depth. It excludes control
records, `UnsupportedElement` instances, and non-drawable B-spline support
records; those remain available through the lossless `drawing.elements`
sequence. `drawing.unsupported_elements` provides a filtered diagnostic view
for unknown kinds. Use `parent()`, `children()`, or `descendants()` when a tree
view is needed.

Ellipse, arc, curve, and B-spline entities retain their native parameters or
control records; they are not flattened to polylines. `parent_index` and
`child_indices` refer to the lossless `drawing.elements` sequence, while
`drawing.parent()`, `children()`, and `descendants()` resolve the objects.
Stored integer UOR, sub-UOR-corrected floating UOR, and optional master-unit
coordinates coexist. `drawing.color_table` is the last type-5, level-1 color
table in file order. `drawing.resolve_color()`, `entity.style.rgb`, and
`fill_rgb` use that table when present and otherwise fall back to the standard
MicroStation V7 256-color palette.

V7 DGN does not record a text code page. `Text.decode_text()` therefore uses
`encoding="ascii", errors="strict"` as a deterministic default; pass the
project encoding explicitly for non-ASCII text.

Known DMRS/database, association ID, shape fill, and high-precision linkages
have typed fields. Unknown user linkages and malformed trailing attribute bytes
remain accessible through read-only raw views. Shared-cell definition/instance
types 34/35 remain raw because the public ISFF chapter does not specify their
layout.

The high-level `read()`/`readfile()` API deliberately rejects V7 3D files.
`scan_records()` and `inspect_headers()` still support bounded inspection of
their shared record framing and metadata.

## Plotting parsed drawings

The optional renderer can display a parsed V7 2D drawing or save it as an
image without changing the native entity model:

```python
import ezdgn

drawing = ezdgn.readfile("drawing.dgn")

figure, axes = ezdgn.plot(
    drawing,
    text_encoding="cp932",
    background="#111111",
)
figure.savefig("preview.png", dpi=150, bbox_inches="tight")

# Or render and save in one call.
ezdgn.save_plot(drawing, "preview.png", text_encoding="cp932")
```

The equivalent CLI command is:

```bash
ezdgn plot drawing.dgn -o preview.png --encoding cp932
```

Omit `-o` to open an interactive Matplotlib window. Use `--monochrome` for a
high-contrast preview, `--hide-text` to suppress text, or
`--coordinate-space uor` when master-unit coordinates are unavailable. Run
`ezdgn plot --help` for the complete option list.

Lines, line strings, shapes, ellipses, arcs, text, and drawable components of
cells and complex elements are rendered. Ellipses and arcs are sampled only
for display. Native type-11 curves and B-spline curves are previewed from
their parsed control sequences; the source records and entity parameters are
never flattened or modified. V7 text does not store its code page, so the
caller must select the correct encoding for non-ASCII text. Geometry and text
with compatible display styles are batched to keep large previews practical.

## V7 writer and optional custom seeds

```python
import ezdgn

doc = ezdgn.new()  # uses the bundled empty V7 2D seed
msp = doc.modelspace()

msp.add_line(
    (0, 0),
    (10, 5),
    dgnattribs={"level": 2, "color": 3, "line_weight": 2},
)
msp.add_line_string([(0, 10), (5, 15), (10, 10)])
msp.add_shape(
    [(20, 0), (30, 0), (30, 10), (20, 10)],
    fill_color=6,
)
msp.add_ellipse((25, 25), primary_axis=5, secondary_axis=3, rotation=30)
msp.add_arc(
    (40, 5),
    primary_axis=5,
    secondary_axis=3,
    start_angle=30,
    sweep_angle=120,
)
msp.add_text("日本語", (0, 30), height=2, encoding="cp932")

doc.saveas("drawing.dgn")
roundtrip = doc.readback()
```

Pass a custom seed as `ezdgn.new("project_seed.dgn")` to use its units, origin,
design plane, and active color table. `new()` copies the mandatory TCB,
digitizer setup, level symbology, and last active color table from the selected
seed. Set `copy_seed_elements=True` to retain every seed record, including any
graphics. Text encoding is not recorded by V7 DGN, so `add_text()` accepts
bytes directly or uses its `encoding="ascii", errors="strict"` defaults for
`str` input.

## Raw record API

```python
import ezdgn

info = ezdgn.detect_format("drawing.dgn")
print(info.kind, info.dimension)

scan = ezdgn.scan_records("drawing.dgn")
print(len(scan.records), scan.termination)

for record in scan.records:
    print(record.offset, record.element_type, record.level, record.raw_bytes)
```

The `V8_CFB` result means that the input has the generic CFB signature used by
V8 DGN files. It is intentionally described as a candidate because the outer
signature alone does not prove that DGN-specific streams are present.

The bounded container inspector verifies the known DGN root markers without
decoding proprietary V8 stream contents:

```python
container = ezdgn.inspect_v8_container("drawing-v8.dgn")
print(container.has_dgn_v8_markers)
print(container.model_storage_paths)
for entry in container.entries:
    print(entry.path, entry.kind, entry.size_bytes)
```

This is structural identification, not V8 entity support or a fidelity
guarantee. `ezdgn.read()`, `readfile()`, and `scan_records()` reject V8 input
instead of silently flattening or converting it. If a workflow converts V8 to
V7 outside `ezdgn`, validate the resulting geometry, text, levels, styles, and
complex/cell relationships before treating it as equivalent to the source.

## Design settings and common headers

```python
import ezdgn

headers = ezdgn.inspect_headers("drawing.dgn")
settings = headers.design_settings

print(settings.master_unit_name, settings.uor_per_master)
print(settings.global_origin_master)

for element in headers.elements:
    common = element.common_header
    if common is not None:
        print(
            element.record.element_type,
            common.range.low_master,
            common.range.high_master,
            common.symbology.color,
        )
```

`read_design_settings()` decodes only the leading TCB. `inspect_headers()`
pairs every raw record with its standard common header when that element type
has one. Attribute bytes remain available as a read-only zero-copy
`ElementMetadata.attribute_view`.

The same inspection is available from the CLI:

```bash
ezdgn inspect drawing.dgn
ezdgn inspect drawing.dgn --records --json
ezdgn inspect drawing.dgn --headers --json
ezdgn inspect drawing.dgn --entities --json
ezdgn inspect drawing-v8.dgn --json
```

## Development

```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install "maturin>=1.13,<2" "pytest>=8" "matplotlib>=3.8"
maturin develop
cargo fmt --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace
python -m pytest
```

Build a distributable wheel with:

```bash
maturin build --release --out dist
```

## License

`ezdgn` is released under the [MIT License](LICENSE). The bundled empty seed
and test fixtures retain the separate upstream terms documented in
[`src/ezdgn/_data/README.md`](src/ezdgn/_data/README.md) and
[`tests/data/dgn/README.md`](tests/data/dgn/README.md).

