# Trace Geometry - 3D Visualization

Beautiful transient geometry display directly in Revit 3D views, integrated with trace logging.

## Overview

The Geometry Visualization system allows you to display transient geometry directly in the Revit 3D view, similar to Dynamo's preview functionality but integrated into your development workflow.

## Supported Geometry Types

- **Faces** - Surface geometry from Revit elements
- **Curves** - Lines, arcs, splines, and complex curve geometry  
- **Solids** - 3D solid geometry with volume
- **Meshes** - Triangulated mesh geometry
- **Points (XYZ)** - Individual points or point collections
- **Bounding Boxes** - Element bounding box visualization
- **Collections** - Multiple geometry objects at once

## Key Features

- **Transient Display** - Uses Revit's DirectContext3D for rendering (inspired by RevitLookup)
- **Manual Control** - Use `ClearGeometry` to remove geometry on demand
- **Performance Optimized** - Efficient rendering and disposal
- **Mixed Geometry Types** - Trace collections of different geometry types in one call
- **Real-time Counter** - Shows number of objects displayed in the `ClearGeometry` button

---

## How to Use

### 1. Enable Geometry Tracing

Ensure the logger is started (geometry tracing is automatically enabled).

### 2. Trace Single Geometry Objects

```csharp
// Trace a face
Face face = GetSomeFace();
Trace.Write(face);

// Trace a curve
Curve curve = GetSomeCurve();
Trace.Write(curve);

// Trace a solid
Solid solid = GetSomeSolid();
Trace.Write(solid);

// Trace a mesh
Mesh mesh = GetSomeMesh();
Trace.Write(mesh);

// Trace a point
XYZ point = new XYZ(10, 20, 30);
Trace.Write(point);

// Trace a bounding box
BoundingBoxXYZ bbox = element.get_BoundingBox(null);
Trace.Write(bbox);
```

### 3. Trace Multiple Geometry Objects

```csharp
// Trace multiple faces
var faces = new List<Face> { face1, face2, face3 };
Trace.Write(faces);

// Trace multiple curves
var curves = selectedElements.SelectMany(e => GetCurvesFromElement(e));
Trace.Write(curves);

// Trace multiple solids
var solids = elements.SelectMany(e => e.GetSolids());
Trace.Write(solids);

// Mixed geometry types
var geometries = new List<GeometryObject> { face, curve, solid };
Trace.Write(geometries);
```

---

## Python/IronPython Usage

```python
import clr
clr.AddReference("RevitAPI")
# For Revit 2025 onward:
clr.AddReference("System.Diagnostics.TraceSource")

from Autodesk.Revit.DB import *
from System.Diagnostics import Trace
from System.Collections.Generic import List

# Trace individual geometry
face = GetSomeFace()  # Your method to get a face
Trace.Write(face)

# Trace collections
curves = List[Curve]()
curves.Add(curve1)
curves.Add(curve2)
Trace.Write(curves)

# Trace points
point = XYZ(10, 20, 30)
Trace.Write(point)
```

---

## Usage Examples

See complete working examples in the repository:

**C# Examples:**
- [CurveVisualization.cs](https://github.com/trgiangv/RevitDevTool/blob/master/source/RevitDevTool.DotnetDemo/CurveVisualization.cs) - Lines, arcs, curves
- [SolidVisualization.cs](https://github.com/trgiangv/RevitDevTool/blob/master/source/RevitDevTool.DotnetDemo/SolidVisualization.cs) - 3D solids
- [FaceVisualization.cs](https://github.com/trgiangv/RevitDevTool/blob/master/source/RevitDevTool.DotnetDemo/FaceVisualization.cs) - Faces and surfaces
- [MeshVisualization.cs](https://github.com/trgiangv/RevitDevTool/blob/master/source/RevitDevTool.DotnetDemo/MeshVisualization.cs) - Mesh geometry
- [XYZVisualization.cs](https://github.com/trgiangv/RevitDevTool/blob/master/source/RevitDevTool.DotnetDemo/XYZVisualization.cs) - Points and axes

**Python Examples:**
- [visualization_curve_script.py](https://github.com/trgiangv/RevitDevTool/blob/master/source/RevitDevTool.PythonDemo/commands/visualization_curve_script.py) - Curve visualization
- [visualization_solid_script.py](https://github.com/trgiangv/RevitDevTool/blob/master/source/RevitDevTool.PythonDemo/commands/visualization_solid_script.py) - Solid visualization
- [visualization_xyz_script.py](https://github.com/trgiangv/RevitDevTool/blob/master/source/RevitDevTool.PythonDemo/commands/visualization_xyz_script.py) - Point visualization

---

## Clearing Visualizations

**From UI:**
- Click the **Clear Geometry** button in the Trace panel
- Number shown indicates how many objects are currently displayed

**From Code:**
```csharp
// Clears all visualized geometry
// (Not exposed via API yet - use UI button)
```

---

## Best Practices

1. **Clear Regularly** - Use Clear Geometry button to avoid cluttering the view
2. **Performance** - Large geometry collections may impact performance
3. **3D View Required** - Geometry only appears in 3D views (not plans/sections)
4. **Document Workflow** - Combine with trace logging for complete debugging

---

## Troubleshooting

### No Geometry Visible
- Ensure logger is enabled
- Verify you're in a 3D view (not 2D plan/section)
- Try toggling Start/Stop Listener

### Geometry Persists
- Use "Clear Geometry" button
- Restart listener if needed

### Performance Issues
- Reduce number of geometry objects traced simultaneously
- Clear geometry between operations
- Use simpler geometry types (curves instead of solids)

---

## Related Topics

- **[Visualization Overview](Visualization-Overview.md)** - Main visualization documentation
- **[Geometry Types](Visualization-GeometryTypes.md)** - Detailed geometry processing