occ-step-geometry

The friendly STEP-reading layer pythonocc never shipped.

Load a STEP file → get clean FaceInfo objects: surface type, area, centre of gravity, sample point & normal, parameter bounds, face-to-face adjacency, and boundary edges.

简体中文 · Why · Install · Quick Start · API

---

Why

pythonocc-core gives you the full power of OpenCASCADE — and its full learning curve. Doing something as basic as "read this STEP file and tell me each face's area, normal, and which faces touch it" means wrangling TopExp_Explorer, BRep_Tool, BRepGProp, GeomLProp_SLProps, surface casts, UV bounds, and orientation flags by hand.

occ-step-geometry is that boilerplate, done once and tested:

from occ_step_geometry import read_step, collect_faces

shape = read_step("part.step")
for f in collect_faces(shape):
    print(f.index, f.type, round(f.area, 1), f.normal, f.adjacent_face_indices)

It returns plain frozen dataclasses (no OCC objects leak into your logic unless you ask for them), so the output is easy to print, diff, serialize, and unit-test.

---

Install

# pythonocc-core ships via conda (it bundles the OpenCASCADE C++ libs)
conda install -c conda-forge pythonocc-core

git clone https://github.com/Rtiming/occ-step-geometry.git
cd occ-step-geometry
pip install -e .          # or just put occ_step_geometry/ on your path

pythonocc-core is distributed through conda-forge, not PyPI. Everything else here is pure Python.

---

Quick Start

from occ_step_geometry import (
    read_step, collect_faces, count_topology, get_bounding_box, print_face_report,
)

shape = read_step("part.step")

print(count_topology(shape))          # (n_faces, n_edges, n_vertices)
bb = get_bounding_box(shape)
print(bb.dx, bb.dy, bb.dz, bb.cx)     # size + center helpers

faces = collect_faces(shape)          # list[FaceInfo]
print_face_report(faces)              # pretty table to stdout

f = faces[0]
f.type                  # "plane" | "cylinder" | "cone" | "sphere" | ...
f.area                  # surface area
f.cog                   # centre of gravity (x, y, z)
f.normal                # representative outward normal
f.uv_bounds             # parameter-domain extent
f.adjacent_face_indices # indices of faces sharing an edge
f.boundary_edges        # per-edge length + endpoints + neighbours

Try it with no file at all — the demo builds an in-memory box:

python examples/inspect_step.py             # demo box
python examples/inspect_step.py part.step   # your file

---

API

Function	Returns
read_step(path)	the OCC TopoDS_Shape for a STEP file
count_topology(shape)	(n_faces, n_edges, n_vertices)
get_bounding_box(shape)	BoundingBox (with dx/dy/dz, cx/cy/cz)
collect_faces(shape, sample_u_count=7, sample_v_count=7)	list[FaceInfo] with adjacency + boundary edges
sample_face_grid(face, u, v) / sample_face_dense(face_info, ...)	grid / dense SurfaceSamples
face_normal_and_sample_point(face)	a robust on-surface point + normal
surface_type_name(face) / face_area(face) / edge_length(edge) / get_uv_bounds(face)	per-primitive queries
print_face_report(faces)	human-readable table

Plus tiny dependency-free 3D helpers: subtract, add, scale, dot, cross, norm, normalize, distance, mean_point, mean_vector, cumulative_polyline_lengths.

All data objects (FaceInfo, BoundingBox, SurfaceSample, UvBounds, BoundaryEdgeInfo, FaceSamplingGrid) are frozen dataclasses.

Notes

• Normals are evaluated on-surface and respect each face's orientation flag.
• Adjacency is built by matching shared edges with a geometric tolerance, so it works on imported STEP solids where topology isn't perfectly sewn.
• Public API and docs are English; some deep implementation comments are bilingual (English / Chinese).

---

Testing

pip install pytest
python -m pytest tests/ -q   # self-contained: builds an OCC box, no STEP file needed

License

MIT