k3d

Grid System Specification (Implemented)

Overview

The grid system provides visual reference and snapping functionality for precise 3D modeling. It includes both a permanent visual grid and temporary guide systems.

1. Visual Grid

1.1 Grid Rendering

• Grid Lines: Rendered as 3D lines in the XY plane at Z=0
• Grid Spacing: Configurable (default: 1.0 unit)
• Grid Extent: Dynamic based on camera position (typically ±20 units)
• Grid Color: Configurable (default: dark gray #595959)
• Grid Line Width: 2 pixels

1.2 Grid Behavior

• Infinite Plane: Grid extends infinitely in X and Y directions
• Reference Only: Grid is visual only and cannot be selected
• Snap Target: Grid intersections are valid snap targets
• Performance: Grid rendering optimized for smooth interaction

2. Grid Snapping

2.1 Snap Types

• Grid Intersection: Snaps to grid line intersections
• Grid Line: Snaps to grid lines (X or Y axis)
• Grid Plane: Snaps to grid plane (Z=0)

2.2 Snap Configuration

• Snap Distance: Configurable tolerance (default: 1e-2 units)
• Snap Priority: Grid snapping has medium priority (3)
• Visual Feedback: Snap indication with cursor changes

3. Guide System

3.1 Grid Guides (G Key)

• Temporary Reference Planes: Created at current cursor position
• Multiple Guides: Supports multiple simultaneous grid guides
• Guide Orientation: Aligned to world axes by default
• Guide Visualization: Semi-transparent planes with grid lines
• Guide Snapping: Full snapping support on guide planes

3.2 Axis Guides (T Key)

• Temporary Reference Axes: Created at current cursor position
• Axis Alignment: Aligned to world X, Y, Z axes
• Guide Lines: Infinite lines along each axis
• Guide Snapping: Snapping to guide lines and intersections
• Color Coding: X=Red, Y=Green, Z=Blue

4. Guide Management

4.1 Guide Creation

• Keyboard Shortcuts: G for grid guides, T for axis guides
• Position: Created at current snap position
• Orientation: Aligned to current snap normal or world axes

4.2 Guide Clearing

• Escape Key: Clears all guides when in Select mode
• Automatic Cleanup: Guides cleared on certain operations
• Guide Limit: Reasonable limit on simultaneous guides

4.3 Guide Behavior

• Persistent: Guides remain until explicitly cleared
• Interactive: Guides can be snapped to and used as reference
• Visual Feedback: Guide highlighting on hover

5. Snap System Integration

5.1 Snap Priority

NONE: 0
FACE: 0
GRID: 3
ENDPOINT: 3
MIDPOINT: 2
LINE: 1
GRID_LINE: 1
GRID_GUIDE: 2
AXIS_GUIDE: 2

5.2 Snap Visualization

• Cursor Feedback: Crosshair changes on valid snap
• Snap Indication: Additional cursor elements for snap type
• Distance Display: Shows snap distance in status bar
• Color Coding: Different colors for different snap types

6. Implementation Details

6.1 Grid Rendering

• ShapeRenderer: Uses libGDX ShapeRenderer for grid lines
• Performance: Optimized line batching
• Camera Alignment: Grid always rendered in world XY plane

6.2 Guide Rendering

• Guide Planes: Rendered as semi-transparent quads
• Guide Lines: Rendered as infinite lines with extent limits
• Guide Extent: Configurable (default: ±10 grid units)

6.3 Snap Computation

• Ray Casting: Grid intersection via ray-plane math
• Line Projection: Grid line snapping via closest point calculation
• Priority System: Weighted snap selection based on distance and type

7. User Interaction

7.1 Keyboard Shortcuts

• G: Create grid guide at cursor
• T: Create axis guide at cursor
• Esc: Clear all guides (in Select mode)

7.2 Visual Feedback

• Grid Highlight: Grid lines highlight on hover
• Guide Highlight: Guides change color when active
• Snap Preview: Shows potential snap points

7.3 Status Information

• Snap Type: Displayed in status bar
• Snap Coordinates: Shows world position
• Guide Count: Shows active guide count

8. Future Enhancements

8.1 Planned Features

• Custom Grid Spacing: User-configurable grid density
• Grid Snapping Toggle: Enable/disable grid snapping
• Guide Transformation: Move/rotate guides interactively
• Guide Persistence: Save/load guides with model

8.2 Performance Improvements

• Grid LOD: Level-of-detail grid rendering
• Guide Optimization: Better guide rendering performance
• Snap Caching: Cache frequent snap calculations

9. Acceptance Criteria

1. Grid Visibility: Grid should be clearly visible but not obstructive
2. Snap Reliability: Grid snapping should be consistent and predictable
3. Guide Creation: Guides should create at expected positions
4. Performance: Grid system should not impact interaction smoothness
5. Visual Feedback: Snap indications should be clear and immediate

This site is open source. Improve this page.