3D Model Export Implementation Strategy


# 3D Model Export Implementation Strategy

This document outlines the strategy for implementing 3D model generation and export capabilities in NeqSim, extending the existing 2D diagram infrastructure.

## Executive Summary

NeqSim's `ProcessDiagramExporter` already provides professional 2D PFD generation. This proposal extends that capability to 3D visualization and CAD-compatible exports, enabling:

- **Web-based 3D visualization** of process plants
- **CAD integration** for engineering workflows
- **BIM compatibility** for construction and operations
- **Digital twin foundations** with real-time process data overlay

## Current State

### Existing 2D Capabilities

| Component | Purpose | Status |
|-----------|---------|--------|
| `ProcessDiagramExporter` | Main export orchestrator | ✅ Implemented |
| `ProcessGraph` / `ProcessGraphBuilder` | Graph representation | ✅ Implemented |
| `PFDLayoutPolicy` | Gravity-based layout | ✅ Implemented |
| `EquipmentVisualStyle` | 2D visual styling | ✅ Implemented |
| `DexpiDiagramBridge` | P&ID data exchange | ✅ Implemented |

### Existing Output Formats

- **DOT** - Graphviz text (pure Java)
- **SVG** - Vector graphics (requires Graphviz)
- **PNG** - Raster image (requires Graphviz)
- **PDF** - Document format (requires Graphviz)

## Proposed Architecture

### New Components

```
neqsim.process.processmodel.visualization/
├── Process3DExporter.java          # Main 3D export orchestrator
├── Equipment3DGeometry.java        # Base class for 3D geometry
├── Equipment3DLibrary.java         # Parametric equipment shapes
├── Process3DScene.java             # Scene graph representation
├── Layout3DPolicy.java             # 3D positioning strategy
├── exporters/
│   ├── GltfExporter.java           # glTF/GLB export
│   ├── StepExporter.java           # STEP/IGES CAD export
│   ├── IfcExporter.java            # IFC BIM export
│   └── Html3DExporter.java         # Self-contained HTML viewer
└── geometry/
    ├── VesselGeometry.java         # Cylindrical vessels
    ├── ColumnGeometry.java         # Distillation columns
    ├── CompressorGeometry.java     # Compressor housings
    ├── HeatExchangerGeometry.java  # Shell & tube, plate
    ├── PipeGeometry.java           # Piping with bends
    ├── ValveGeometry.java          # Valve bodies
    └── PumpGeometry.java           # Pump casings
```

### Class Diagram

```
┌─────────────────────┐
│   ProcessSystem     │
└─────────┬───────────┘
          │ creates
          ▼
┌─────────────────────┐      ┌──────────────────────┐
│ Process3DExporter   │─────▶│  Process3DScene      │
└─────────┬───────────┘      │  - nodes: List       │
          │                  │  - connections: List │
          │ uses             │  - boundingBox       │
          ▼                  └──────────────────────┘
┌─────────────────────┐
│ Equipment3DLibrary  │
│ - getGeometry(type) │
└─────────┬───────────┘
          │ returns
          ▼
┌─────────────────────┐      ┌──────────────────────┐
│ Equipment3DGeometry │      │ MechanicalDesign     │
│ - vertices          │◀─────│ - dimensions         │
│ - faces             │      │ - materials          │
│ - materials         │      └──────────────────────┘
└─────────────────────┘
```

## Output Formats

### Priority 1: glTF/GLB (Web 3D)

**Why glTF:**
- Industry standard for web 3D ("JPEG of 3D")
- Supported by Three.js, Babylon.js, Unity, Unreal, Blender
- Compact binary format (GLB)
- Includes materials, textures, animations

**Library options:**
- [JglTF](https://github.com/javagl/JglTF) - Pure Java glTF library
- Custom minimal implementation (glTF is JSON-based)

```java
// Proposed API
Process3DExporter exporter = new Process3DExporter(processSystem);
exporter.setScale(1.0)                    // 1 unit = 1 meter
        .setIncludePiping(true)           // Include pipe routing
        .setColorScheme(ColorScheme.PHASE) // Color by phase
        .exportGLTF(Path.of("plant.glb"));
```

### Priority 2: HTML Viewer (Zero Dependencies)

Self-contained HTML file with embedded Three.js:

```java
// Proposed API
exporter.exportHtmlViewer(Path.of("plant_viewer.html"));
// Opens in any modern browser with pan/zoom/rotate
```

**Features:**
- No server required (file:// works)
- Interactive camera controls
- Equipment selection/highlighting
- Process data tooltips (T, P, flow)
- Phase flow animation (optional)

### Priority 3: STEP/IGES (CAD Integration)

For integration with SolidWorks, AutoCAD, CATIA:

```java
// Proposed API - per-equipment export
MechanicalDesign design = separator.getMechanicalDesign();
design.calcDesign();
design.exportToSTEP(Path.of("separator.step"));

// Proposed API - full plant
exporter.exportSTEP(Path.of("plant.step"));
```

**Library options:**
- [Open CASCADE](https://www.opencascade.com/) via JNI (heavyweight)
- [JCAE/Occjava](https://github.com/occjava) - Java bindings for OpenCASCADE
- Command-line FreeCAD integration

### Priority 4: IFC (BIM)

For construction, facility management, and digital twins:

```java
exporter.exportIFC(Path.of("plant.ifc"), IfcSchema.IFC4);
```

**Library options:**
- [BIMserver](https://github.com/opensourceBIM/BIMserver) IfcEngine
- [IFC.js](https://ifcjs.io/) via GraalJS
- [IfcOpenShell](http://ifcopenshell.org/) command-line

## Equipment Geometry Library

### Parametric Shapes

Equipment geometry is generated from mechanical design dimensions:

| Equipment Type | Base Shape | Parameters |
|----------------|------------|------------|
| Separator | Cylinder + heads | D, L, head type |
| Column | Tall cylinder + trays | D, H, tray count |
| Compressor | Box + inlet/outlet | Power-based sizing |
| Heat Exchanger | Shell + tubes | Shell D, tube count |
| Pump | Casing + impeller | Flow-based sizing |
| Valve | Body + actuator | Cv-based sizing |
| Tank | Cylinder + roof | D, H, roof type |
| Pipe | Extruded circle | OD, wall, path |

### Geometry Generation Example

```java
public class VesselGeometry extends Equipment3DGeometry {
    
    @Override
    public void generateFromDesign(MechanicalDesign design) {
        double innerD = design.getInnerDiameter();
        double length = design.getTanTanLength();
        double wallT = design.getWallThickness();
        
        // Generate cylinder body
        addCylinder(innerD/2 + wallT, length, 32); // 32 segments
        
        // Generate heads (elliptical 2:1)
        addEllipticalHead(innerD/2 + wallT, HeadType.ELLIPTICAL_2_1, true);
        addEllipticalHead(innerD/2 + wallT, HeadType.ELLIPTICAL_2_1, false);
        
        // Add nozzles based on connections
        for (Nozzle nozzle : design.getNozzles()) {
            addNozzle(nozzle.getPosition(), nozzle.getDiameter(), nozzle.getLength());
        }
    }
}
```

### Default Sizing (No Mechanical Design)

When `MechanicalDesign` is not available, use heuristic sizing:

```java
public class DefaultEquipmentSizer {
    
    public Dimensions estimateSize(ProcessEquipmentInterface equipment) {
        if (equipment instanceof Separator) {
            Separator sep = (Separator) equipment;
            double volumeFlow = sep.getGasOutStream().getFlowRate("m3/hr");
            // Heuristic: 3-minute residence time
            double volume = volumeFlow * 3.0 / 60.0;
            double diameter = Math.pow(volume / (Math.PI * 3), 1.0/3.0); // L/D = 3
            return new Dimensions(diameter, diameter * 3);
        }
        // ... other equipment types
    }
}
```

## 3D Layout Strategy

### Option A: Flattened PFD Layout (Simple)

Project the existing 2D PFD layout to 3D:
- X = horizontal position (left-to-right flow)
- Y = elevation (gas up, liquid down)
- Z = 0 (all on same plane)

```java
Layout3DPolicy flatLayout = new FlattenedPFDLayout();
exporter.setLayoutPolicy(flatLayout);
```

### Option B: Plot Plan Layout (Realistic)

Equipment positioned based on typical plant layout:
- Separation train in center
- Compressors on one side (noise considerations)
- Flare at safe distance
- Control room location

```java
Layout3DPolicy plotPlan = new PlotPlanLayout()
    .setPlotDimensions(100, 80)  // meters
    .setMinEquipmentSpacing(3.0)
    .setFlareDistance(50.0);
exporter.setLayoutPolicy(plotPlan);
```

### Option C: User-Defined Coordinates

Import layout from external source:

```java
Map<String, Point3D> positions = new HashMap<>();
positions.put("HP Separator", new Point3D(10, 0, 5));
positions.put("Compressor", new Point3D(25, 0, 8));

Layout3DPolicy custom = new CustomLayout(positions);
exporter.setLayoutPolicy(custom);
```

## Piping Routing

### Simple Routing (Phase 1)

Direct connections with single bend:

```java
PipeRouter simpleRouter = new SimplePipeRouter();
// Creates L-shaped connections between equipment
```

### Manhattan Routing (Phase 2)

Orthogonal routing with pipe racks:

```java
PipeRouter manhattanRouter = new ManhattanPipeRouter()
    .setPipeRackElevation(6.0)  // meters
    .setMinBendRadius(5.0);     // 5D minimum
```

### Spline Routing (Phase 3)

Smooth curves for visualization:

```java
PipeRouter splineRouter = new SplinePipeRouter()
    .setSmoothness(0.8);
```

## Integration with Mechanical Design

The 3D exporter leverages existing `MechanicalDesign` classes:

```java
// Equipment with mechanical design
Separator separator = new Separator("HP Sep", feed);
separator.initMechanicalDesign();

SeparatorMechanicalDesign design = 
    (SeparatorMechanicalDesign) separator.getMechanicalDesign();
design.setMaxOperationPressure(85.0);
design.setMaterialGrade("SA-516-70");
design.calcDesign();

// 3D export uses calculated dimensions
Process3DExporter exporter = new Process3DExporter(process);
exporter.setUseDesignDimensions(true);  // Use mechanical design
exporter.exportGLTF(Path.of("plant.glb"));
```

## Implementation Phases

### Phase 1: Foundation (4-6 weeks)

**Deliverables:**
- [ ] `Process3DExporter` base class
- [ ] `Process3DScene` graph representation
- [ ] `Equipment3DGeometry` base class
- [ ] Basic equipment shapes (vessel, box, cylinder)
- [ ] glTF export (minimal viable)
- [ ] Unit tests

**API available after Phase 1:**
```java
String gltf = process.to3DGLTF();  // JSON string
process.export3DGLTF(Path.of("plant.glb"));  // Binary file
```

### Phase 2: Equipment Library (4-6 weeks)

**Deliverables:**
- [ ] Parametric vessel geometry (heads, nozzles)
- [ ] Column geometry with tray indicators
- [ ] Compressor/pump geometry
- [ ] Heat exchanger geometry
- [ ] Valve geometry
- [ ] Integration with `MechanicalDesign`

### Phase 3: HTML Viewer (2-3 weeks)

**Deliverables:**
- [ ] Self-contained HTML template
- [ ] Embedded Three.js (minified)
- [ ] Camera controls (orbit, pan, zoom)
- [ ] Equipment selection
- [ ] Process data tooltips
- [ ] Color schemes (phase, temperature, pressure)

**API available after Phase 3:**
```java
process.export3DViewer(Path.of("plant.html"));
```

### Phase 4: Piping (3-4 weeks)

**Deliverables:**
- [ ] Pipe geometry generation
- [ ] Simple L-routing
- [ ] Manhattan routing with pipe racks
- [ ] Pipe sizing from flow data
- [ ] Insulation indication

### Phase 5: CAD Export (6-8 weeks)

**Deliverables:**
- [ ] STEP export integration
- [ ] IGES export
- [ ] IFC export for BIM
- [ ] Per-equipment export option

### Phase 6: Advanced Features (Ongoing)

- [ ] Animation (flow direction, phase)
- [ ] Real-time data connection
- [ ] VR/AR export (WebXR)
- [ ] Cloud rendering option
- [ ] Import from CAD (reverse engineering)

## Dependencies

### Required (Phase 1)

| Library | Purpose | License |
|---------|---------|---------|
| [JglTF](https://github.com/javagl/JglTF) | glTF generation | MIT |

### Optional (Later Phases)

| Library | Purpose | License |
|---------|---------|---------|
| [JOML](https://github.com/JOML-CI/JOML) | 3D math (vectors, matrices) | MIT |
| [Open CASCADE](https://www.opencascade.com/) | STEP/IGES export | LGPL |
| [IfcOpenShell](http://ifcopenshell.org/) | IFC export | LGPL |

### Maven Dependencies (Phase 1)

```xml
<dependency>
    <groupId>de.javagl</groupId>
    <artifactId>jgltf-model</artifactId>
    <version>2.0.3</version>
</dependency>
<dependency>
    <groupId>org.joml</groupId>
    <artifactId>joml</artifactId>
    <version>1.10.5</version>
</dependency>
```

## Python/Jupyter Integration

```python
from neqsim import jneqsim
from IPython.display import IFrame, HTML

# Build and run process
process = jneqsim.process.processmodel.ProcessSystem("Gas Plant")
# ... add equipment ...
process.run()

# Export 3D viewer
process.export3DViewer("plant_3d.html")

# Display inline in Jupyter
IFrame("plant_3d.html", width=800, height=600)
```

## Example: Complete Workflow

```java
// 1. Build process model
ProcessSystem process = new ProcessSystem("Offshore Gas Platform");

Stream wellStream = new Stream("Well Stream", feedFluid);
wellStream.setFlowRate(50000, "kg/hr");
process.add(wellStream);

ThreePhaseSeparator hpSep = new ThreePhaseSeparator("HP Separator", wellStream);
process.add(hpSep);

Compressor comp = new Compressor("Export Compressor", hpSep.getGasOutStream());
comp.setOutletPressure(150.0, "bara");
process.add(comp);

// 2. Run simulation
process.run();

// 3. Initialize mechanical design
hpSep.initMechanicalDesign();
hpSep.getMechanicalDesign().calcDesign();

// 4. Export 2D PFD
process.createDiagramExporter()
    .setDetailLevel(DiagramDetailLevel.ENGINEERING)
    .exportSVG(Path.of("platform_pfd.svg"));

// 5. Export 3D model
Process3DExporter exporter3D = new Process3DExporter(process);
exporter3D.setUseDesignDimensions(true)
          .setIncludePiping(true)
          .setColorScheme(ColorScheme.PHASE)
          .setLayoutPolicy(new PlotPlanLayout());

// Multiple output formats
exporter3D.exportGLTF(Path.of("platform.glb"));      // For web viewers
exporter3D.exportHtmlViewer(Path.of("platform.html")); // Self-contained
exporter3D.exportSTEP(Path.of("platform.step"));     // For CAD
exporter3D.exportIFC(Path.of("platform.ifc"));       // For BIM
```

## Success Metrics

| Metric | Target |
|--------|--------|
| Export time (100 equipment) | < 5 seconds |
| GLB file size (100 equipment) | < 10 MB |
| HTML viewer load time | < 3 seconds |
| Equipment type coverage | > 90% |
| Mechanical design integration | 100% where available |

## Risks and Mitigations

| Risk | Impact | Mitigation |
|------|--------|------------|
| OpenCASCADE complexity | STEP export delayed | Start with glTF, add CAD later |
| Large model performance | Slow visualization | LOD (Level of Detail) support |
| Geometry accuracy | Engineering rejection | Validate against P&ID standards |
| Browser compatibility | Limited reach | Test on Chrome, Firefox, Safari, Edge |

## Related Documentation

- [Process Flow Diagram Export](diagram_export.md) - Existing 2D export
- [DEXPI XML Reader](../../integration/dexpi-reader.md) - P&ID import
- [Mechanical Design Pattern](../../.github/copilot-instructions.md#mechanical-design-implementation-pattern-mandatory) - Design dimensions

## Conclusion

This implementation strategy provides a phased approach to 3D visualization that:

1. **Builds on existing infrastructure** - Reuses `ProcessGraph`, `MechanicalDesign`, layout concepts
2. **Delivers value early** - Phase 1 provides usable glTF export
3. **Scales to enterprise needs** - CAD/BIM integration in later phases
4. **Supports multiple use cases** - Web visualization, engineering review, digital twins

The recommended starting point is **Phase 1 (glTF export)** followed immediately by **Phase 3 (HTML viewer)** to provide a complete, zero-dependency visualization solution.


Component	Purpose	Status
`ProcessDiagramExporter`	Main export orchestrator	✅ Implemented
`ProcessGraph` / `ProcessGraphBuilder`	Graph representation	✅ Implemented
`PFDLayoutPolicy`	Gravity-based layout	✅ Implemented
`EquipmentVisualStyle`	2D visual styling	✅ Implemented
`DexpiDiagramBridge`	P&ID data exchange	✅ Implemented

Equipment Type	Base Shape	Parameters
Separator	Cylinder + heads	D, L, head type
Column	Tall cylinder + trays	D, H, tray count
Compressor	Box + inlet/outlet	Power-based sizing
Heat Exchanger	Shell + tubes	Shell D, tube count
Pump	Casing + impeller	Flow-based sizing
Valve	Body + actuator	Cv-based sizing
Tank	Cylinder + roof	D, H, roof type
Pipe	Extruded circle	OD, wall, path

Library	Purpose	License
JOML	3D math (vectors, matrices)	MIT
Open CASCADE	STEP/IGES export	LGPL
IfcOpenShell	IFC export	LGPL

Metric	Target
Export time (100 equipment)	< 5 seconds
GLB file size (100 equipment)	< 10 MB
HTML viewer load time	< 3 seconds
Equipment type coverage	> 90%
Mechanical design integration	100% where available

Risk	Impact	Mitigation
OpenCASCADE complexity	STEP export delayed	Start with glTF, add CAD later
Large model performance	Slow visualization	LOD (Level of Detail) support
Geometry accuracy	Engineering rejection	Validate against P&ID standards
Browser compatibility	Limited reach	Test on Chrome, Firefox, Safari, Edge

3D Model Export Implementation Strategy #1864

Description

3D Model Export Implementation Strategy

Executive Summary

Current State

Existing 2D Capabilities

Existing Output Formats

Proposed Architecture

New Components

Class Diagram

Output Formats

Priority 1: glTF/GLB (Web 3D)

Priority 2: HTML Viewer (Zero Dependencies)

Priority 3: STEP/IGES (CAD Integration)

Priority 4: IFC (BIM)

Equipment Geometry Library

Parametric Shapes

Geometry Generation Example

Default Sizing (No Mechanical Design)

3D Layout Strategy

Option A: Flattened PFD Layout (Simple)

Option B: Plot Plan Layout (Realistic)

Option C: User-Defined Coordinates

Piping Routing

Simple Routing (Phase 1)

Manhattan Routing (Phase 2)

Spline Routing (Phase 3)

Integration with Mechanical Design

Implementation Phases

Phase 1: Foundation (4-6 weeks)

Phase 2: Equipment Library (4-6 weeks)

Phase 3: HTML Viewer (2-3 weeks)

Phase 4: Piping (3-4 weeks)

Phase 5: CAD Export (6-8 weeks)

Phase 6: Advanced Features (Ongoing)

Dependencies

Required (Phase 1)

Optional (Later Phases)

Maven Dependencies (Phase 1)

Python/Jupyter Integration

Example: Complete Workflow

Success Metrics

Risks and Mitigations

Related Documentation

Conclusion

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions