kompas-kernel 0.0.1__py3-none-any.whl

kompas_kernel/features/geometry_3d/ksapi/component_geometry.py

@@ -0,0 +1,559 @@
+"""Component resolution + exact geometry primitives: axis, mesh, planar/cylindrical B-rep facts.
+
+Free functions taking explicit `modules`/`app` dependencies (no adapter `self` state),
+matching the same facade-vs-implementation split as `features/assembly_navigator/ksapi/
+reader.py`. `KompasSession` owns `modules`/`app`/the worker; this module never reaches
+back into session state.
+
+`resolve_component`/`component_by_identifier` are the ONE place the "identifier ->
+`IPart`" convention lives for this slice's KsAPI modules (`measurements.py` and
+`presentation.py` both import them from here, hence the public — no leading underscore
+— names, same precedent as `kompas.objects`) — replacing what used to be six near-
+identical `doc3d`/`top`/`components`/`_component_by_identifier` preambles duplicated
+across `measure_min_distance`/`find_neighbors`/`component_axis`/`component_mesh`/
+`component_planar_faces`/`component_cylindrical_faces`/`show_distance_dimension`
+(E16.04a dedup step, before the split from legacy `bridge/kompas_ksapi/geometry.py`).
+
+`_global_corners`/`_collect_face_facts` are the second dedup: `component_planar_faces`
+and `component_cylindrical_faces` used to duplicate the SAME six-branch face-enumeration
+loop (type predicate → tolerance gate → corner transform → append-or-skip) with only the
+per-surface-type math (`IsPlanar`/`_face_plane_local` vs `IsCylinder`/`_cylinder_axis_local`/
+`GetRadius`) actually differing. `_collect_face_facts` owns the shared loop/corner-transform
+skeleton; each caller supplies only its own `compute(face) -> radial_mm | None` closure.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import math
+from collections.abc import Callable
+from typing import Any
+
+from kompas_kernel.features.geometry_3d.models import (
+    AxisLine,
+    ComponentMesh,
+    CylindricalFaceFact,
+    CylindricalFaces,
+    FaceMesh,
+    PlanarFaceFact,
+    PlanarFaces,
+)
+from kompas_kernel.kompas.errors import KompasError
+from kompas_kernel.kompas.models import Point3D
+from kompas_kernel.kompas.objects import as_document_3d, constants3d_class, parse_index
+from kompas_kernel.kompas.runtime import KsApiModules
+from kompas_kernel.observability.logger import get_logger
+from kompas_kernel.observability.taxonomy import LogDomain, LogEventType, event_name
+
+logger = get_logger(__name__)
+
+_KSAPI_BOOL_XYZ_VALUE_COUNT = 4
+_POINT3D_COORDINATE_COUNT = 3
+# |dot(face plane normal, query axis direction)| below this ⇒ plane parallel to the axis
+# (a side wall, not a torec/скос) — exact geometry, so the tolerance only absorbs float noise.
+_PLANE_PARALLEL_TO_AXIS_TOLERANCE = 1e-3
+# |abs(dot(cylinder axis direction, query axis direction)) - 1| below this ⇒ the two axes
+# are parallel (within float noise) — a cylindrical wall whose own axis runs alongside
+# the query axis, not a bore/fillet crossing it at an angle.
+_CYLINDER_AXIS_PARALLEL_TOLERANCE = 1e-3
+
+
+def component_by_identifier(operation: str, components: list[Any], identifier: str) -> Any:
+    index = parse_index(identifier)
+    if index is None or not (0 <= index < len(components)):
+        raise KompasError(f"{operation}: component identifier {identifier!r} is invalid")
+    return components[index]
+
+
+def resolve_assembly(modules: KsApiModules, app: Any, operation: str) -> tuple[Any, Any, list[Any]]:
+    """`(doc3d, top, components)` of the active 3D document's assembly, or raise `KompasError`.
+
+    `doc3d` is returned alongside `top`/`components` (not just discarded internally)
+    because `presentation.py::show_distance_dimension` needs it later for
+    `GetSelectionManager()` — recomputing the same cheap `IKompasDocument3D` cast a
+    second time would work too (it is a pure interface cast, no KsAPI side effect), but
+    returning it here avoids a second call and a second (dead, since the first already
+    proved it succeeds) not-3D guard at the call site.
+    """
+    doc3d = as_document_3d(modules, app.GetActiveDocument())
+    if doc3d is None:
+        raise KompasError(f"{operation}: активный документ не 3D")
+    constants3d = constants3d_class(modules)
+    top = doc3d.GetTopPart()
+    components: list[Any] = list(top.GetPartsArray(int(constants3d.ksAllParts)))
+    return doc3d, top, components
+
+
+def resolve_component(
+    modules: KsApiModules, app: Any, operation: str, identifier: str
+) -> tuple[Any, Any, list[Any], Any]:
+    """`(doc3d, top, components, component)` for `identifier`, or raise `KompasError`.
+
+    Shared preamble for every geometry query/command that resolves exactly one component
+    identifier before doing its own work — a caller resolving a SECOND identifier from the
+    same assembly reuses the returned `components` list with `component_by_identifier`
+    directly (`measure_min_distance`/`show_distance_dimension` in the sibling modules),
+    rather than calling this twice and re-walking `GetPartsArray`.
+    """
+    doc3d, top, components = resolve_assembly(modules, app, operation)
+    component = component_by_identifier(operation, components, identifier)
+    return doc3d, top, components, component
+
+
+def bool_xyz_point(raw: Any) -> Point3D | None:
+    """Parse a KsAPI `(ok, x, y, z)` out-param tuple into `Point3D`, or `None` if not ok.
+
+    Shared shape across several unrelated KsAPI calls that all follow the same
+    convention (`IPlacement3D.GetOrigin`/`GetVector`, `IMeasurement3D.GetMinPoint1/2`)
+    — one parser, not one per call site (GPC8).
+    """
+    values = tuple(raw) if raw is not None else ()
+    if len(values) < _KSAPI_BOOL_XYZ_VALUE_COUNT or not bool(values[0]):
+        return None
+    return Point3D(x_mm=float(values[1]), y_mm=float(values[2]), z_mm=float(values[3]))
+
+
+def _points_from_flat(values: list[float]) -> list[Point3D] | None:
+    """Group a flat `[x0, y0, z0, x1, y1, z1, ...]` list into `Point3D` triples."""
+    if len(values) < _POINT3D_COORDINATE_COUNT or len(values) % _POINT3D_COORDINATE_COUNT != 0:
+        return None
+    return [
+        Point3D(x_mm=values[i], y_mm=values[i + 1], z_mm=values[i + 2])
+        for i in range(0, len(values), _POINT3D_COORDINATE_COUNT)
+    ]
+
+
+def _face_tessellation_points(face: Any, top: Any, component: Any) -> list[Point3D] | None:
+    """Tessellation points of one face, transformed into the assembly's global CS (mm).
+
+    `IFace.GetTessellation().GetFacetPoints()` + `IPart.TransformPoints()` call
+    sequence; feeds `component_mesh` and `nearest_face`. A face without tessellation
+    (or any KsAPI failure along the way) is a graceful `None`, not an exception —
+    callers skip it.
+    """
+    tessellation = face.GetTessellation()
+    if not tessellation:
+        return None
+    with contextlib.suppress(Exception):
+        ok, raw_points, _indices, _normals = tessellation.GetFacetPoints([], [], [])
+        if bool(ok):
+            transformed_ok, transformed_points = top.TransformPoints([float(point) for point in raw_points], component)
+            if bool(transformed_ok):
+                return _points_from_flat([float(point) for point in transformed_points])
+    return None
+
+
+def _component_faces(modules: KsApiModules, component: Any) -> list[Any]:
+    constants3d = constants3d_class(modules)
+    container = component.GetModelContainer()
+    if container is None:
+        return []
+    raw_faces = container.GetObjects(int(constants3d.o3d_face))
+    if raw_faces is None:
+        return []
+    faces: list[Any] = []
+    for raw_face in raw_faces:
+        face = modules.ksapi.IFace(raw_face)
+        if face:
+            faces.append(face)
+    return faces
+
+
+def _subtract(a: Point3D, b: Point3D) -> Point3D:
+    return Point3D(x_mm=a.x_mm - b.x_mm, y_mm=a.y_mm - b.y_mm, z_mm=a.z_mm - b.z_mm)
+
+
+def _dot(a: Point3D, b: Point3D) -> float:
+    return a.x_mm * b.x_mm + a.y_mm * b.y_mm + a.z_mm * b.z_mm
+
+
+def _normalize(v: Point3D) -> Point3D | None:
+    length = math.sqrt(v.x_mm**2 + v.y_mm**2 + v.z_mm**2)
+    if length == 0:
+        return None
+    return Point3D(x_mm=v.x_mm / length, y_mm=v.y_mm / length, z_mm=v.z_mm / length)
+
+
+def _axis_in_local_frame(top: Any, component: Any, axis: AxisLine) -> tuple[Point3D, Point3D] | None:
+    """Transform a global `AxisLine` into `component`'s own local body frame.
+
+    `component.TransformPoint(x, y, z, top)` — called on the TARGET frame (`component`),
+    with `top` as the frame the given `(x, y, z)` are expressed in (AGENTS.md §«Точная
+    трансформация локальная → глобальная СК» — same method as the corner transform
+    elsewhere in this module, used here in the opposite direction: global→local of an
+    arbitrary component, not local→global). Direction cannot be point-transformed
+    directly (translation would corrupt it) — recovered by transforming a SECOND point
+    along the axis and subtracting, which cancels the translation and leaves the rotated
+    direction (AGENTS.md строки 176-178).
+    """
+    local_origin = bool_xyz_point(component.TransformPoint(axis.origin.x_mm, axis.origin.y_mm, axis.origin.z_mm, top))
+    far_global = Point3D(
+        x_mm=axis.origin.x_mm + axis.direction.x_mm,
+        y_mm=axis.origin.y_mm + axis.direction.y_mm,
+        z_mm=axis.origin.z_mm + axis.direction.z_mm,
+    )
+    local_far = bool_xyz_point(component.TransformPoint(far_global.x_mm, far_global.y_mm, far_global.z_mm, top))
+    if local_origin is None or local_far is None:
+        return None
+    unit_direction = _normalize(_subtract(local_far, local_origin))
+    if unit_direction is None:
+        return None
+    return local_origin, unit_direction
+
+
+def _cylinder_axis_local(modules: KsApiModules, face: Any) -> tuple[Point3D, Point3D] | None:
+    """Exact (origin, unit direction) of a cylindrical face's surface axis, component's OWN local body frame.
+
+    `IFace.GetMathSurface().GetPlacement()` → `GetOrigin()`/`GetVector(o3d_axisOZ)` — same
+    origin+direction shape as `IPlacement3D` elsewhere in this module. Confirmed live
+    (spike, 2026-07-08, see `docs/recipes/ksapi-link.md`) to be in the face's OWN LOCAL
+    body frame for a component's face — exactly like `GetPoint`/`GetNormal`
+    (AGENTS.md §«KsAPI: точный B-rep»), NOT already the assembly's global CS. An earlier
+    spike's opposite conclusion tested only a non-rotated component, where local and
+    global numerically coincide — it could not actually distinguish the two hypotheses
+    (see that spike's erratum). Caller must already have confirmed `face.IsCylinder()`.
+    """
+    surface = face.GetMathSurface()
+    if not surface:
+        return None
+    placement = surface.GetPlacement()
+    if not placement:
+        return None
+    origin = bool_xyz_point(placement.GetOrigin(0.0, 0.0, 0.0))
+    direction = bool_xyz_point(placement.GetVector(int(constants3d_class(modules).o3d_axisOZ), 0.0, 0.0, 0.0))
+    if origin is None or direction is None:
+        return None
+    unit_direction = _normalize(direction)
+    if unit_direction is None:
+        return None
+    return origin, unit_direction
+
+
+def _face_plane_local(face: Any) -> tuple[Point3D, Point3D] | None:
+    """Exact (normal, point-on-plane) of a planar face, sampled once at its own param midpoint.
+
+    `IFace.GetNormal`/`GetPoint` evaluate the underlying analytic surface directly — no
+    tessellation. Param midpoint (`GetParamUMin/UMax`+`GetParamVMin/VMax`, averaged) sits
+    inside any simple 4-edge trimmed face (a hex flat's straight-sided rectangle), so this
+    never samples outside the face's own boundary. Both points/vectors are in the
+    component's OWN LOCAL body frame (see AGENTS.md §«KsAPI: точный B-rep вместо
+    меша/тесселляции» — `IFace` methods are NOT in the assembly's global CS). Caller must
+    already have confirmed `face.IsPlanar()` — for a planar face the normal is constant
+    over (u, v), so one sample fully determines the plane; for any other surface type this
+    would just be the local tangent, not useful here.
+    """
+    u_mid = (face.GetParamUMin() + face.GetParamUMax()) / 2.0
+    v_mid = (face.GetParamVMin() + face.GetParamVMax()) / 2.0
+    normal = bool_xyz_point(face.GetNormal(u_mid, v_mid, 0.0, 0.0, 0.0))
+    point = bool_xyz_point(face.GetPoint(u_mid, v_mid, 0.0, 0.0, 0.0))
+    if normal is None or point is None:
+        return None
+    length = math.sqrt(normal.x_mm**2 + normal.y_mm**2 + normal.z_mm**2)
+    if length == 0:
+        return None
+    unit_normal = Point3D(x_mm=normal.x_mm / length, y_mm=normal.y_mm / length, z_mm=normal.z_mm / length)
+    return unit_normal, point
+
+
+def _face_param_box_corners_local(face: Any) -> list[Point3D] | None:
+    """Four corner points of a planar face's own parameter box, exact surface points, local frame.
+
+    Approximates the trimmed boundary by its parameter-range corners — exact for a
+    simple 4-edge rectangular flat (a hex side wall), not a general trim (a face with a
+    curved or non-rectangular loop would need `GetLoops()`/edge vertices instead — out of
+    scope here, see `component_planar_faces` docstring).
+
+    Two known strangenesses, carried over verbatim from the legacy module (E16.04a,
+    behavior-preserving split — not bugs of THIS function, do not "fix" them here):
+    corners come back in `(u_min,v_min), (u_min,v_max), (u_max,v_min), (u_max,v_max)`
+    order, which is NOT a contour walk (sequential connection self-intersects into a
+    "bowtie") — safe today because both callers (`eyes/hex_detect.py`, `eyes/wrench_zone.py`)
+    only take min/max of projections and `corners[0]`, order does not matter to them.
+    """
+    u_min, u_max = face.GetParamUMin(), face.GetParamUMax()
+    v_min, v_max = face.GetParamVMin(), face.GetParamVMax()
+    corners: list[Point3D] = []
+    for u, v in ((u_min, v_min), (u_min, v_max), (u_max, v_min), (u_max, v_max)):
+        point = bool_xyz_point(face.GetPoint(u, v, 0.0, 0.0, 0.0))
+        if point is None:
+            return None
+        corners.append(point)
+    return corners
+
+
+def _global_corners(face: Any, top: Any, component: Any) -> list[Point3D] | None:
+    """A face's own parameter-box corners (local frame), transformed to the assembly's global CS.
+
+    Shared by `component_planar_faces`/`component_cylindrical_faces` (E16.04a dedup):
+    `IPart.TransformPoint` is called on `top`, with `component` as the frame the raw
+    local corners are expressed in — the OPPOSITE direction of `_axis_in_local_frame`
+    above (local component -> global assembly, not global -> local). `None` as soon as
+    ANY corner fails to transform (matches the legacy per-caller loop's `break` +
+    length-mismatch check: a partially-transformed face was never used, only fully
+    transformed-or-skipped).
+    """
+    local_corners = _face_param_box_corners_local(face)
+    if local_corners is None:
+        return None
+    global_corners: list[Point3D] = []
+    for local_point in local_corners:
+        transformed = bool_xyz_point(
+            top.TransformPoint(local_point.x_mm, local_point.y_mm, local_point.z_mm, component)
+        )
+        if transformed is None:
+            return None
+        global_corners.append(transformed)
+    return global_corners
+
+
+def _collect_face_facts(
+    faces: list[Any],
+    compute: Callable[[Any], float | None],
+    *,
+    top: Any,
+    component: Any,
+) -> list[tuple[int, float, list[Point3D]]]:
+    """Shared face-enumeration skeleton: `(face_index, radial_mm, global_corners)` triples.
+
+    `compute(face)` is the ONLY part that differs between `component_planar_faces`
+    (`IsPlanar`/`_face_plane_local`) and `component_cylindrical_faces` (`IsCylinder`/
+    `_cylinder_axis_local`/`GetRadius`) — it returns this face's `radial_mm` if the face
+    passes the caller's type/tolerance gate, or `None` to skip it (non-matching surface
+    type, degenerate sample, torec/скос not parallel to the axis). Corner computation and
+    the transform-to-global-CS are identical for both surface kinds and live here once.
+    """
+    results: list[tuple[int, float, list[Point3D]]] = []
+    for face_index, face in enumerate(faces):
+        radial_mm = compute(face)
+        if radial_mm is None:
+            continue
+        corners = _global_corners(face, top, component)
+        if corners is None:
+            continue
+        results.append((face_index, radial_mm, corners))
+    return results
+
+
+def nearest_face(modules: KsApiModules, component: Any, top: Any, target: Point3D) -> Any | None:
+    """Resolve the `IFace` of `component` whose tessellation has the vertex nearest `target`.
+
+    The fast `measure_min_distance` mechanism (`IMeasurement3D`, part<->part) does not
+    return the winning face pair, but the permanent `IDistanceAngleMeasurement3D` feature
+    only accepts `IFace<->IFace`. This resolves a face by nearest tessellated vertex to
+    the fast measurement's own min-distance point — same `component_mesh` mechanic
+    (`_component_faces` + `_face_tessellation_points`), reused here instead of duplicated
+    (GPC8). Chordal tessellation error can occasionally pick a neighboring face over the
+    mathematically exact one — acceptable for a highlight, not for a measured fact (see
+    `ShowDistanceResult` docstring on `shown_value_mm`).
+    """
+    best_face: Any | None = None
+    best_distance_sq: float | None = None
+    for face in _component_faces(modules, component):
+        points = _face_tessellation_points(face, top, component)
+        if points is None:
+            continue
+        for point in points:
+            dx = point.x_mm - target.x_mm
+            dy = point.y_mm - target.y_mm
+            dz = point.z_mm - target.z_mm
+            distance_sq = dx * dx + dy * dy + dz * dz
+            if best_distance_sq is None or distance_sq < best_distance_sq:
+                best_distance_sq = distance_sq
+                best_face = face
+    return best_face
+
+
+def component_axis(modules: KsApiModules, app: Any, identifier: str) -> AxisLine:
+    """Component axis: origin point + direction, global document CS, mm.
+
+    Spike 01: `IPlacement3D.GetVector(o3d_axisOZ)` is the direct, recommended way
+    to get the local-Z axis direction of a component's placement (not a manual
+    `GetMatrix3D()` parse, which risks a row-major/column-major mixup on rotated
+    components). For standard library fasteners, `GetOrigin()` lands on the
+    reference plane under the head/nut.
+    """
+    _doc3d, _top, _components, component = resolve_component(modules, app, "component_axis", identifier)
+
+    placement = component.GetPlacement()
+    if not placement:
+        raise KompasError(f"component_axis: component {identifier!r} has no placement")
+    origin = bool_xyz_point(placement.GetOrigin(0.0, 0.0, 0.0))
+    if origin is None:
+        raise KompasError(f"component_axis: GetOrigin() failed for component {identifier!r}")
+    direction = bool_xyz_point(placement.GetVector(int(constants3d_class(modules).o3d_axisOZ), 0.0, 0.0, 0.0))
+    if direction is None:
+        raise KompasError(f"component_axis: GetVector(o3d_axisOZ) failed for component {identifier!r}")
+
+    logger.info(
+        event_name(LogDomain.BRIDGE, "ksapi_component_axis", LogEventType.COMPLETED),
+        identifier=identifier,
+    )
+    return AxisLine(origin=origin, direction=direction)
+
+
+def component_mesh(modules: KsApiModules, app: Any, identifier: str) -> ComponentMesh:
+    """Tessellation points of every face of a component, global document CS, mm.
+
+    Reuses the `GetTessellation().GetFacetPoints()` + `IPart.TransformPoints()`
+    mechanic that also feeds `nearest_face`. Faces without tessellation are skipped,
+    not errors.
+    """
+    _doc3d, top, _components, component = resolve_component(modules, app, "component_mesh", identifier)
+
+    faces = _component_faces(modules, component)
+    face_meshes: list[FaceMesh] = []
+    for face_index, face in enumerate(faces):
+        points = _face_tessellation_points(face, top, component)
+        if points is None:
+            continue
+        face_meshes.append(FaceMesh(face_index=face_index, points=points))
+
+    logger.info(
+        event_name(LogDomain.BRIDGE, "ksapi_component_mesh", LogEventType.COMPLETED),
+        identifier=identifier,
+        face_count=len(faces),
+        faces_with_tessellation=len(face_meshes),
+    )
+    return ComponentMesh(faces=face_meshes)
+
+
+def component_planar_faces(modules: KsApiModules, app: Any, identifier: str, axis: AxisLine) -> PlanarFaces:
+    """Exact planar side-wall faces of a component parallel to `axis`, global document CS, mm.
+
+    For each face: `IFace.IsPlanar()` gates out every non-planar surface (cylinder,
+    cone, fillet, freeform — see AGENTS.md §«KsAPI: точный B-rep вместо
+    меша/тесселляции», `GetSurface3DType()` proved unreliable, `Is*()` predicates
+    didn't). For planar faces, `_face_plane_local` samples the underlying analytic
+    plane once (normal + a point on it) at the face's own parameter midpoint — exact,
+    not a tessellation fit. A face is kept only if its plane is parallel to `axis`
+    (`|dot(normal, unit axis direction)|` below tolerance) — a torec/скос face has no
+    single well-defined radial distance and is not a side wall.
+
+    `axis` need not be `identifier`'s own axis: calling this with a FASTENER's axis
+    while `identifier` is one of its NEIGHBORS finds the neighbor's walls parallel to
+    the fastener, which is what a wrench-clearance radial fact needs (`eyes.wrench_zone`).
+    Calling it with `component_axis(identifier)` (the component's own axis) reproduces
+    the original hex-detection use (`eyes.hex_detect`) — that case is not a special
+    branch, just this same code with a particular `axis` value: `_axis_in_local_frame`
+    transforms `axis.origin`/`origin+direction` into `identifier`'s local frame via
+    `component.TransformPoint(x, y, z, top)`, and for a component's OWN axis that
+    transform trivially yields local `(0,0,0)`/`(0,0,1)` — the previous hardcoded
+    assumption, now a special case rather than baked in.
+
+    Coordinate frame: `IFace` methods operate in the component's OWN LOCAL body frame,
+    not the assembly's global CS (unlike `component_axis`/`component_mesh`, which are
+    already transformed) — see AGENTS.md §«KsAPI: точный B-rep». `radial_mm` is
+    computed in this local frame using the axis ALSO expressed there
+    (`_axis_in_local_frame`) — a plane-to-line distance, frame-invariant in magnitude,
+    and (because the plane is parallel to the axis) independent of which point on the
+    axis is used: for axis direction `d` with `dot(normal, d) = 0`, every point `O` on
+    the axis gives the same `dot(point_on_plane - O, normal)` as `O` varies by `t*d`
+    (that extra term is `t * dot(d, normal) = 0`). `corners` (the face's parameter-box
+    corners, `_face_param_box_corners_local`) ARE transformed to the assembly's global
+    CS via `_global_corners` so the caller can project them onto the global `axis`
+    without knowing about this function's local-frame internals.
+    """
+    _doc3d, top, _components, component = resolve_component(modules, app, "component_planar_faces", identifier)
+
+    local_axis = _axis_in_local_frame(top, component, axis)
+    if local_axis is None:
+        raise KompasError(f"component_planar_faces: could not transform axis into local frame of {identifier!r}")
+    local_origin, unit_local_direction = local_axis
+
+    def _planar_radial_mm(face: Any) -> float | None:
+        if not bool(face.IsPlanar()):
+            return None
+        plane = _face_plane_local(face)
+        if plane is None:
+            return None
+        normal, point_on_plane = plane
+        if abs(_dot(normal, unit_local_direction)) > _PLANE_PARALLEL_TO_AXIS_TOLERANCE:
+            return None  # торец/скос — не боковая стенка призмы
+        return abs(_dot(_subtract(point_on_plane, local_origin), normal))
+
+    faces = _component_faces(modules, component)
+    facts = [
+        PlanarFaceFact(face_index=face_index, radial_mm=radial_mm, corners=corners)
+        for face_index, radial_mm, corners in _collect_face_facts(
+            faces, _planar_radial_mm, top=top, component=component
+        )
+    ]
+
+    logger.info(
+        event_name(LogDomain.BRIDGE, "ksapi_component_planar_faces", LogEventType.COMPLETED),
+        identifier=identifier,
+        face_count=len(faces),
+        planar_side_faces=len(facts),
+    )
+    return PlanarFaces(faces=facts)
+
+
+def component_cylindrical_faces(modules: KsApiModules, app: Any, identifier: str, axis: AxisLine) -> CylindricalFaces:
+    """Exact cylindrical faces of a component whose axis is parallel to `axis`, global document CS, mm.
+
+    Sibling of `component_planar_faces` for the ROUND pocket-corner case of ГОСТ
+    13682-80 Черт. 5 (R — the radius a wrench needs to turn in). For each face:
+    `IFace.IsCylinder()` gates non-cylindrical surfaces; `GetRadius()` gives the exact
+    radius (no fitting — call only after `IsCylinder()` confirmed true, it has no
+    success flag); `_cylinder_axis_local` gives the cylinder's own axis via
+    `GetMathSurface().GetPlacement()`, in the SAME local body frame as `_face_plane_local`
+    (confirmed live — see that function's docstring). A face is kept only if its own
+    axis is parallel to `axis` (within `_CYLINDER_AXIS_PARALLEL_TOLERANCE`) — a bore or
+    fillet crossing `axis` at an angle has no single radial distance from it.
+
+    `radial_mm = abs(axis_to_axis_mm - radius_mm)`: `axis_to_axis_mm` is the radial
+    component (`eyes.wrench_zone`-style axis projection, computed inline here — this
+    module does not import `eyes`) of the cylinder axis's origin relative to `axis`, in
+    the shared local frame; since the two axes are parallel, this is the same for any
+    point picked on the cylinder axis. `abs(d - R)` is the distance from a point (the
+    projection of `axis` onto the cross-section plane) to a circle of radius `R` —
+    correct whether `axis` runs inside or outside the cylinder, no sign/side reasoning
+    needed. Confirmed live (spike, 2026-07-08): matched two independently known
+    reference distances on the same demo assembly exactly (6.0 mm and 16.0 mm).
+
+    `corners` — same `_global_corners` transform to global CS as `component_planar_faces`,
+    reused verbatim.
+    """
+    _doc3d, top, _components, component = resolve_component(modules, app, "component_cylindrical_faces", identifier)
+
+    local_axis = _axis_in_local_frame(top, component, axis)
+    if local_axis is None:
+        raise KompasError(f"component_cylindrical_faces: could not transform axis into local frame of {identifier!r}")
+    local_origin, unit_local_direction = local_axis
+
+    def _cylindrical_radial_mm(face: Any) -> float | None:
+        if not bool(face.IsCylinder()):
+            return None
+        cylinder_axis = _cylinder_axis_local(modules, face)
+        if cylinder_axis is None:
+            return None
+        cylinder_origin, unit_cylinder_direction = cylinder_axis
+        alignment = abs(_dot(unit_cylinder_direction, unit_local_direction))
+        if abs(alignment - 1.0) > _CYLINDER_AXIS_PARALLEL_TOLERANCE:
+            return None  # ось цилиндра не параллельна запрошенной оси — вне охвата этого fast-path
+        radius_mm = float(face.GetRadius())
+        delta = _subtract(cylinder_origin, local_origin)
+        axial_mm = _dot(delta, unit_local_direction)
+        radial_vector = Point3D(
+            x_mm=delta.x_mm - axial_mm * unit_local_direction.x_mm,
+            y_mm=delta.y_mm - axial_mm * unit_local_direction.y_mm,
+            z_mm=delta.z_mm - axial_mm * unit_local_direction.z_mm,
+        )
+        axis_to_axis_mm = math.sqrt(radial_vector.x_mm**2 + radial_vector.y_mm**2 + radial_vector.z_mm**2)
+        return abs(axis_to_axis_mm - radius_mm)
+
+    faces = _component_faces(modules, component)
+    facts = [
+        CylindricalFaceFact(face_index=face_index, radial_mm=radial_mm, corners=corners)
+        for face_index, radial_mm, corners in _collect_face_facts(
+            faces, _cylindrical_radial_mm, top=top, component=component
+        )
+    ]
+
+    logger.info(
+        event_name(LogDomain.BRIDGE, "ksapi_component_cylindrical_faces", LogEventType.COMPLETED),
+        identifier=identifier,
+        face_count=len(faces),
+        cylindrical_faces=len(facts),
+    )
+    return CylindricalFaces(faces=facts)