Utility_Apps/Blender/addons/Mesh Outline Projector/README.md

# Mesh Outline Projector

A Blender addon that projects the vertical outline of selected objects onto a target mesh and transfers materials, perfect for architectural visualization and terrain mapping.

## Overview

Mesh Outline Projector takes the 2D silhouette of objects (when viewed from above) and "stamps" them onto a mesh below, automatically cutting the mesh and applying the source object's material to the projected area. Think of it as a cookie-cutter that works vertically through 3D space.

### Key Features

- **Vertical Projection**: Projects object outlines straight down (Z-axis) onto target surfaces
- **Material Transfer**: Automatically applies source object materials to projected regions
- **Clean Cutting**: Uses Blender's knife project for precise edge creation
- **Smart Material Assignment**: Point-in-polygon detection with edge tolerance for accurate coverage
- **Mesh Cleanup**: Automatically removes previous cuts with Limit Dissolve
- **Intersection Detection**: Validates that objects actually overlap before processing
- **Multiple Objects**: Process multiple source objects in a single operation

## Installation

1. Download `mesh_outline_projector.py`
2. Open Blender → Edit → Preferences → Add-ons
3. Click "Install..." and select the downloaded file
4. Enable "Mesh: Mesh Outline Projector" in the add-ons list
5. The panel appears in the 3D Viewport sidebar under the "Outline Projector" tab

## Quick Start

### Basic Workflow

1. **Setup Scene**
   - Position your source objects (e.g., building footprints) above your target mesh (e.g., terrain)
   - Objects can be at any height - only horizontal (XY) overlap matters

2. **Select Objects**
   - Select one or more source objects (the objects whose outlines you want to project)
   - Select the target mesh **last** (it becomes the active object - shown in orange)

3. **Set View**
   - Press **Numpad 7** to switch to top orthographic view
   - This is required for knife project to work correctly

4. **Run Operator**
   - Open the sidebar (N key) → "Outline Projector" tab
   - Adjust settings if needed (see below)
   - Click "Project Outline"

### What Happens

The addon performs these steps automatically:

1. **Validates** that source objects overlap with target in XY plane
2. **Cleans up** the target mesh (Limit Dissolve + Quads to Tris)
3. **Resets materials** to the first material slot
4. **For each source object**:
   - Extracts the horizontal perimeter edges (2D outline)
   - Creates a temporary curve from these edges
   - Uses knife project to cut the target mesh
   - Assigns the source material to faces within the projected area
5. **Reports** results with detailed console output

## Settings

### Dissolve Angle

- **Default**: 0.04 degrees
- **Range**: 0.0 - 5.0 degrees
- **Purpose**: Controls how aggressively Limit Dissolve removes edges from previous operations

**When to adjust:**
- **Increase** (0.5-2.0°) if working with curved or organic surfaces
- **Keep low** (0.01-0.1°) for architectural/flat surfaces
- Higher values = more aggressive cleanup, fewer edges

### Edge Tolerance

- **Default**: 0.05 units
- **Range**: 0.0 - 1.0 units
- **Purpose**: How close a vertex must be to a polygon edge to be considered "on the edge"

**When to adjust:**
- **Increase** (0.1-0.5) if missing faces at the boundaries
- **Decrease** (0.01-0.03) if getting material bleeding outside the outline
- Affects the precision of material assignment at polygon boundaries

## Use Cases

### Architectural Site Plans

Project building footprints onto terrain meshes:
- Import IFC building models
- Create terrain mesh from topography data
- Project building outlines to create material zones

### Terrain Texturing

Stamp different material zones onto landscapes:
- Roads, paths, and sidewalks
- Water bodies and wetlands
- Vegetation zones
- Building pads

### Urban Planning

Visualize zoning and land use:
- Different materials for residential/commercial/industrial zones
- Overlay multiple boundary shapes
- Iterate quickly as plans change

## Tips & Best Practices

### Before Running

✅ **Do:**
- Ensure source objects are above or at the same level as target mesh
- Use simple, clean geometry for source objects
- Press Numpad 7 (top view) before running
- Save your work before first use

❌ **Don't:**
- Use extremely complex source meshes (simplify first)
- Forget to set top view
- Run on unsaved files (though Undo works)

### Iteration Workflow

The addon is designed for iteration:

1. Run projection with objects A and B
2. Adjust position/scale of object A
3. Run projection again - mesh is automatically cleaned up
4. Materials from both objects are preserved

**The mesh reset happens automatically** - you can run the operator multiple times without manual cleanup.

### Material Management

- The addon preserves the **first material slot** as the "base" material
- Source materials are added as new slots (slot 1, 2, 3, etc.)
- Each run resets everything to the base material before applying projections
- If you want a different base material, assign it to slot 0 before running

## Troubleshooting

### "No source objects intersect with target mesh"

**Problem**: Objects don't overlap in the XY plane (when viewed from above)

**Solutions**:
- Check bounding boxes in debug output
- Move objects horizontally to overlap
- Objects can be at different Z heights - that's fine
- Ensure you're not selecting the target as a source object

### Materials not appearing correctly

**Problem**: Materials bleeding outside boundaries or missing at edges

**Solutions**:
- Adjust **Edge Tolerance** setting
- Increase if missing edge faces (try 0.1-0.2)
- Decrease if bleeding outside (try 0.02-0.03)
- Check that source objects have materials assigned

### Blender crashes

**Problem**: Crash during operation (rare)

**Solutions**:
- Ensure you're in **top orthographic view** (Numpad 7)
- Simplify source mesh geometry
- Update to latest Blender version
- Check console for error messages

### Unexpected results after multiple runs

**Problem**: Results look different on subsequent runs

**Solutions**:
- This is normal - each run subdivides the mesh differently
- Knife project creates new edges each time
- Undo (Ctrl+Z) to return to previous state
- The dissolve/cleanup helps but won't make mesh identical

## Technical Details

### How Outline Detection Works

The addon uses three methods to find outline edges:

1. **Boundary edges**: Edges with only one connected face
2. **Silhouette edges**: Edges where connected faces have different vertical orientations
3. **Perimeter edges**: Vertical edges at the outer boundary

These are combined to form the complete 2D outline when viewed from above.

### Material Assignment Algorithm

1. **Extract horizontal edges** from the 3D outline
2. **Build a 2D polygon** from these edges (in world XY space)
3. **For each face** in the target mesh:
   - Check if **all vertices** are inside the polygon OR near an edge
   - Uses ray-casting for point-in-polygon test
   - Uses perpendicular distance for edge proximity
4. **Assign material** only if all vertices pass

This ensures clean boundaries without bleeding.


## Known Limitations

- Requires **top orthographic view** (Numpad 7) to work correctly
- Works best with **relatively flat** target meshes
- Very **dense meshes** may slow down processing
- **Complex source geometry** may produce unexpected outlines
- Knife project can create **overlapping edges** in some cases
- **Z-axis projection only** - cannot project at angles