ViewDesignEngine/docs/feedback/VDE-101.md

VDE-101: 3D Annotation / PMI — Model-Based Definition (MBD)

Date: 2026-07-31 Severity: High (industry transition to paperless manufacturing) Status: Closed — Out of Scope — belongs in ViewDesign application layer, not in VDE kernel

Summary

Model-Based Definition (MBD) is the practice of annotating 3D CAD models with all product manufacturing information (PMI) — dimensions, tolerances, surface finish, material, notes — directly in the 3D model instead of on 2D drawings.

This is an industry megatrend driven by:

• ASME Y14.41 (Digital Product Definition Data Practices)
• ISO 16792 (Digital product definition data practices)
• MIL-STD-31000 (Technical Data Packages — DoD mandate)
• Boeing/Airbus digital transformation (no 2D drawings for new programs)

Industry leaders:

• SolidWorks MBD (model-based definition module)
• CATIA 3D Tolerance & Annotation (FTA)
• NX PMI (Product Manufacturing Information)
• Creo MBD

VDE has:

• brep/brep.h — 3D geometry
• basic logging/text services

But lacks any 3D annotation framework.

Gap Analysis

Missing:

• Annotation planes (planar, cylindrical, conical annotation surfaces)
• Dimension types: linear, angular, radial, diametral, chamfer, ordinate
• GD&T feature control frames (flatness, parallelism, position, etc.)
• Datum target symbols (datum planes, axes, points)
• Surface finish symbols (Ra, Rz, lay direction)
• Weld symbols (per AWS A2.4 / ISO 2553)
• Note/flag note/text annotations
• Balloon/revision symbols
• Annotation views (capture specific 3D views with annotations)
• Semantic PMI (machine-readable, not just visual)
• STEP AP242 export with semantic PMI
• 3D PDF / JT export with embedded PMI

Proposed API

namespace vde::brep {

/// Annotation plane type
enum class AnnotationPlaneType {
    Planar,            ///< annotation on a flat plane
    Cylindrical,       ///< annotation wrapped on cylinder
    Conical,           ///< annotation on cone surface
};

/// Annotation plane definition
struct AnnotationPlane {
    AnnotationPlaneType type;
    Plane3D plane;                     ///< for planar
    Cylinder cylinder;                 ///< for cylindrical
    std::string name;                  ///< e.g., "Front View", "Section A-A"
};

/// Dimension types
enum class DimType {
    Linear,              ///< distance between two points/lines/planes
    Linear_Horizontal,   ///< horizontal component only
    Linear_Vertical,     ///< vertical component only
    Angular,             ///< angle between two lines/planes
    Radial,              ///< radius of arc/circle/cylinder
    Diametral,           ///< diameter with Ø symbol
    Chamfer,             ///< chamfer dimension (C2 or 2×45°)
    Ordinate,            ///< baseline dimensioning
    ArcLength,           ///< curved length
    HoleCallout,         ///< simplified hole callout
};

/// Dimension annotation
struct DimAnnotation {
    DimType type;
    
    // References
    int face_id_1, face_id_2;          ///< referenced geometry faces
    int edge_id;                       ///< for radial/diametral
    Point3D attachment_point_1;        ///< first witness line attachment
    Point3D attachment_point_2;        ///< second witness line attachment
    
    // Value
    double nominal_value;              ///< mm or degrees (calculated or overridden)
    bool override_value = false;       ///< manually entered value?
    
    // Tolerance
    double upper_tol;
    double lower_tol;
    bool is_symmetric_tol = true;      ///< ± tolerance vs. separate upper/lower
    std::string tol_class;             ///< "H7", "g6", etc. (ISO fit)
    
    // Display
    Point3D text_position;            ///< where the dimension text appears
    int precision = 2;                ///< decimal places
    
    // Modifiers
    bool is_basic = false;            ///< [BASIC] per ASME Y14.5
    bool is_reference = false;        ///< (REF) reference dimension
    bool is_inspection = false;       ///< inspection dimension
};

/// GD&T feature control frame
struct GDTFrame {
    // Tolerance type
    enum GeoType {
        // Form
        Straightness, Flatness, Circularity, Cylindricity,
        // Profile
        ProfileOfLine, ProfileOfSurface,
        // Orientation
        Parallelism, Perpendicularity, Angularity,
        // Location
        Position, Concentricity, Symmetry,
        // Runout
        CircularRunout, TotalRunout,
    };
    GeoType type;
    
    // Tolerance value
    double tolerance_mm;
    std::string tolerance_zone_shape;  ///< "Ø" for cylindrical, "" for planar
    
    // Material condition modifiers
    enum MaterialCondition { RFS, MMC, LMC };
    MaterialCondition condition = RFS;
    
    // Datum references (up to 3)
    struct DatumRef {
        std::string datum_label;       ///< "A", "B", "C"
        MaterialCondition condition = RFS;
    };
    std::vector<DatumRef> datums;
    
    // Composite frame (lower segment for pattern location)
    bool has_composite_frame = false;
    double composite_tolerance = 0.0;
    
    // Projected tolerance zone
    double projected_height = 0.0;     ///< 0 = none
    
    /// Serialize to STEP AP242 semantic PMI
    [[nodiscard]] std::string to_step242() const;
};

/// Datum definition
struct DatumDef {
    std::string label;                 ///< "A", "B", "C"
    enum DatumType { Plane, Axis, Point, Line };
    DatumType type;
    int face_id;                       ///< referenced face
    Point3D location;                  ///< datum symbol position
    bool is_primary = false;           ///< primary datum
};

/// Surface finish symbol
struct SurfaceFinish {
    std::string method;                ///< e.g., "Ra 3.2", "Rz 25"
    double ra_value_um;                ///< μm
    double rz_value_um = 0.0;
    std::string machining_allowance;   ///< "0.5", "MIN"
    std::string lay_direction;         ///< "=" (parallel), "⊥" (perpendicular), "M" (multi)
    bool is_all_over = false;          ///< applies to entire part
    int face_id;                       ///< specific face (ignored if all_over)
    Point3D position;                  ///< symbol position
};

/// Annotation view (captured 3D view)
struct AnnotationView {
    std::string name;                  ///< "Front", "ISO", "Detail A"
    Point3D camera_position;
    Point3D camera_target;
    Vector3D camera_up;
    double zoom_level = 1.0;
    AnnotationPlane plane;
    
    // Annotations in this view
    std::vector<DimAnnotation> dimensions;
    std::vector<GDTFrame> gdt_frames;
    std::vector<DatumDef> datums;
    std::vector<SurfaceFinish> surface_finishes;
    std::vector<std::string> notes;    ///< plain text notes
    
    bool is_section_view = false;
    Plane3D section_plane;             ///< if section
};

/// PMI Manager
class PMIManager {
public:
    /// Add annotation view
    int add_view(const AnnotationView& view);

    /// Add dimension to a view
    void add_dimension(int view_id, const DimAnnotation& dim);

    /// Add GD&T frame to a view
    void add_gdt_frame(int view_id, const GDTFrame& frame);

    /// Add datum to a view
    void add_datum(int view_id, const DatumDef& datum);

    /// Add surface finish to a view
    void add_surface_finish(int view_id, const SurfaceFinish& finish);

    /// Add note
    void add_note(int view_id, const std::string& note);

    // ── Export ──

    /// Export as STEP AP242 with semantic PMI
    [[nodiscard]] bool export_step242_pmi(
        const std::string& filepath,
        const BrepModel& body);

    /// Export as 3D PDF with embedded PMI
    [[nodiscard]] bool export_3dpdf_pmi(
        const std::string& filepath,
        const BrepModel& body);

    /// Export as JT with PMI
    [[nodiscard]] bool export_jt_pmi(
        const std::string& filepath,
        const BrepModel& body);
};

} // namespace vde::brep

STEP AP242 Integration

STEP AP242 is the ISO standard for model-based definition with semantic PMI:

AP242 entity:  product_definition_with_associated_documents
  ├── shape_representation (geometry from AP203/214)
  ├── dimensional_characteristic_representation
  │   ├── dimensional_location (Ø, distance)
  │   ├── dimensional_size (linear, angular, radius)
  │   ├── datum (datum_plane, datum_axis, datum_point)
  │   └── geometric_tolerance (flatness, position, etc.)
  ├── surface_texture (Ra, Rz, lay)
  └── annotation_occurrence (visual placement)

Use Cases

1. Aerospace: Boeing 787/777X program — all-new designs are MBD-only
2. Automotive: 3D tolerancing for body-in-white assembly
3. Defense: MIL-STD-31000A compliant technical data packages
4. Medical: FDA-compliant design history with semantic annotations
5. Tooling: CAM programmer reads tolerances directly from 3D model

Industry Standards

• ASME Y14.5-2018 (GD&T) + Y14.41-2019 (Digital Product Definition)
• ISO 1101 (GPS — Geometrical Product Specifications)
• ISO 16792 (Digital product definition data practices)
• STEP AP242 (Managed Model-Based 3D Engineering)
• MIL-STD-31000B (Technical Data Packages)

References

• VDE brep/gdt.h — GD&T annotations (pre-existing, but static only)
• VDE brep/brep.h — B-Rep geometry (reference for annotation attachment)
• ISO 10303-242 — STEP AP242 specification