ApprenticeFoundryWorldsAndDrawings 25.2.0

FoundryWorldsAndDrawings

A unified C# / Blazor library that combines 2D Canvas and 3D WebGL visualization capabilities, replacing both FoundryBlazor and BlazorThreeJS with a single, integrated solution.

🏷️ NuGet Package: ApprenticeFoundryWorldsAndDrawings
🎯 Version: 24.3.0
🔧 Framework: .NET 9.0
📄 License: MIT

📋 Table of Contents

• Overview
• Features
• Pivot Point System
• Installation
• Quick Start
• Documentation
• Architecture Highlights
• Migration Guide
• Examples
• Requirements
• Troubleshooting
• Deployment
• Support

🎯 Overview

FoundryWorldsAndDrawings is the next-generation unified library that brings together 2D diagramming and 3D visualization in Blazor applications. Built using the Strangler Fig migration pattern, it maintains full backward compatibility while providing enhanced functionality and better architecture.

🔄 Migration from Legacy Libraries

This package replaces:

• ✅ FoundryBlazor (2D Canvas diagramming)
• ✅ BlazorThreeJS (3D WebGL rendering)

Benefits of Migration:

• 🚀 Single Package: One library instead of multiple dependencies
• 🎭 Arena-Scene Bridge: More reliable 3D object management
• 🎬 Enhanced Animations: Better animation system with dirty flagging
• 📁 Unified Static Assets: Standardized asset pipeline
• 🔧 Simplified Setup: Single service registration

✨ Features

2D Capabilities

• Canvas2D Rendering: Complete shape library with advanced drawing capabilities
• Interactive Diagrams: Mouse/touch interactions, pan/zoom, selection
• Glued Connections: Dynamic connections that maintain relationships
• Multi-page Support: Scaled diagrams across multiple pages

3D Capabilities

• WebGL Rendering: High-performance 3D graphics using Three.js
• 3D Model Loading: GLB/GLTF asset support with FoModel3D wrapper
• Animation System: SetAnimationUpdate callbacks with proper dirty flagging
• Transform System: Unified position, rotation, scale with matrix operations
• Pivot Point Support: Objects rotate and scale around custom pivot points for precise positioning
• Center of Gravity Control: Change rotation and scaling anchors for all primitives and models
• Camera Controls: Orbit, pan, zoom camera interactions

Unified Features

• Arena Pattern: Reliable 3D object management with Scene bridge
• Cross-platform: Works in both Blazor Server and WebAssembly
• Performance Optimized: Object pooling, dirty flagging, efficient rendering
• TypeScript Integration: Seamless JavaScript interop

🎯 Pivot Point System & Center of Gravity

FoundryWorldsAndDrawings provides comprehensive pivot point support for all 3D shapes and primitives, allowing you to change the center of gravity for rotation and scaling operations. This enables precise positioning and natural transformations.

📐 Supported Primitives with Pivot Support

All primitive shapes support custom pivot points through the Transform.Pivot property:

Basic Primitives

• FoBox - Rectangular boxes, cubes
• FoSphere - Spherical objects
• FoCylinder - Cylindrical shapes, tubes
• FoCone - Cone and pyramid shapes
• FoPlane - Flat surfaces, walls, floors
• FoCapsule - Rounded cylindrical shapes

Advanced Primitives

• FoTorus - Donut/ring shapes
• FoTorusKnot - Complex twisted torus
• FoRing - Flat circular rings
• FoTetrahedron - 4-sided polyhedron
• FoOctahedron - 8-sided polyhedron
• FoIcosahedron - 20-sided polyhedron
• FoDodecahedron - 12-sided polyhedron

Complex Objects

• FoModel3D - Loaded GLB/GLTF models
• FoText3D - 3D text objects
• FoPipe3D - Tube/pipe systems
• FoGroup3D - Grouped object collections

🎮 Pivot Point Examples

// Create a box that sits on the ground (bottom pivot)
var groundBox = new FoShape3D().CreateBox("GroundBox", 2, 2, 2);
groundBox.Transform.Pivot = new Vector3(0, -1, 0);  // Bottom center
groundBox.Transform.Position = new Vector3(0, 1, 0); // Box bottom at Y=0

// Create a door that swings on hinges (edge pivot)  
var door = new FoShape3D().CreateBox("Door", 0.1, 2.0, 1.0);
door.Transform.Pivot = new Vector3(-0.5, 0, 0);      // Left edge pivot
door.Transform.Rotation = new Vector3(0, openAngle, 0); // Swings around hinge

// Create a ceiling light (top pivot)
var light = new FoModel3D("CeilingLight")
{
    Transform = new Transform3("LightTransform")
    {
        Pivot = new Vector3(0, 1, 0),           // Top center pivot
        Position = new Vector3(0, 3, 0),        // Hangs from ceiling
        Rotation = new Vector3(0, 0, swayAngle) // Sways from top
    }
};

// Create a wheel that rolls (bottom edge contact)
var wheel = new FoShape3D().CreateCylinder("Wheel", 1, 0.2, 1);
wheel.Transform.Pivot = new Vector3(0, -0.5, 0);     // Bottom contact point
wheel.Transform.RotateBy(rollSpeed, 0, 0);           // Rolls around contact

🎯 Common Pivot Patterns

💡 Coordinate System: Pivot values are in normalized local coordinates (-1 to 1), where (0,0,0) is the object center.

Key Dependencies

• ApprenticeFoundryRulesAndUnits (9.2.0) - Mathematical foundations and unit system
• Blazor.Extensions.Canvas (1.1.1) - 2D Canvas rendering support
• BlazorComponentBus (2.2.0) - Component communication and messaging
• Radzen.Blazor (8.0.4) - UI components and dialogs
• SkiaSharp (3.119.0) - Advanced 2D graphics rendering

📦 Installation

dotnet add package ApprenticeFoundryWorldsAndDrawings

📋 NuGet Package: ApprenticeFoundryWorldsAndDrawings

Current Version: 24.4.0 (targeting .NET 9.0)

🚀 Quick Start

1. Service Registration

// Program.cs - Single registration replaces multiple libraries
using FoundryWorldsAndDrawings;

var builder = WebApplication.CreateBuilder(args);

// Add unified services (replaces AddFoundryBlazorServices + AddBlazorThreeJSServices)
var envConfig = new EnvConfig("./.env");
builder.Services.AddFoundryWorldsAndDrawingsServices(envConfig);

var app = builder.Build();

// Enable static file serving for 3D models
app.UseStaticFiles();

2. Basic 3D Component

@page "/my3d"
@using FoundryWorldsAndDrawings.ThreeD.Viewers
@using FoundryWorldsAndDrawings.Shared
@using FoundryWorldsAndDrawings.Solutions
@rendermode InteractiveServer

<h3>My 3D Scene</h3>

<div class="d-flex">
    <Canvas3DComponent SceneName="MyScene" @ref="Canvas3DReference" CanvasWidth="1200" CanvasHeight="800" />
    <div class="controls">
        <button class="btn btn-primary" @onclick="AddModel">Add 3D Model</button>
        <button class="btn btn-success" @onclick="StartAnimation">Start Animation</button>
    </div>
</div>

@code {
    [Inject] public IWorkspace Workspace { get; set; } = null!;
    [Inject] public NavigationManager Navigation { get; set; } = null!;
    
    public Canvas3DComponent Canvas3DReference = null!;
    
    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            // Establish Arena-Scene bridge
            var (found, scene) = Canvas3DReference?.GetActiveScene() ?? (false, null!);
            var arena = Workspace.GetArena();
            if (found) arena.SetScene(scene!);
        }
    }
    
    public void AddModel()
    {
        // Arena pattern - recommended approach
        var shape = new FoModel3D("MyModel")
        {
            Url = GetReferenceTo(@"storage/StaticFiles/model.glb"),
            Transform = new Transform3("ModelTransform")
            {
                Position = new Vector3(0, 0, 0),
                Scale = new Vector3(1, 1, 1),
                // Pivot examples (normalized coordinates -1 to 1):
                // Pivot = new Vector3(0, -1, 0),     // Bottom pivot (object sits on ground)
                // Pivot = new Vector3(0, 0, 0),      // Center pivot (default, rotate around center)  
                // Pivot = new Vector3(-1, 0, 0),     // Left edge pivot (rotate around left side)
            }
        };
        
        // Also create a primitive box with bottom pivot
        var groundBox = new FoShape3D("GroundBox").CreateBox("Box", 1, 1, 1);
        groundBox.Transform.Pivot = new Vector3(0, -0.5, 0); // Bottom center pivot
        groundBox.Transform.Position = new Vector3(2, 0.5, 0); // Box sits on ground
        
        var arena = Workspace.GetArena();
        arena.AddShapeToStage<FoModel3D>(shape);
        arena.AddShapeToStage<FoShape3D>(groundBox);
    }
    
    public void StartAnimation()
    {
        // Add animation to existing objects
        var arena = Workspace.GetArena();
        var shapes = arena.GetShapes<FoModel3D>();
        
        foreach (var shape in shapes)
        {
            shape.SetAnimationUpdate((self, tick, fps) =>
            {
                // Rotate around Y axis
                self.Transform.RotateBy(0, 0.01, 0, AngleUnit.Radians);
                self.SetDirty(self.Transform.IsDirty);
            });
        }
    }
    
    public string GetReferenceTo(string filename)
    {
        return Path.Combine(Navigation.BaseUri, filename);
    }
}

3. Static Asset Setup

# Place 3D models in:
wwwroot/storage/StaticFiles/
├── model.glb
├── texture.jpg
└── other-assets.*

📚 Documentation

Migration Guides

• Migration Guide - Complete step-by-step migration from legacy libraries
• Architecture Guide - Technical architecture and design patterns
• Quick Reference - Fast migration reference and common patterns

Technical Documentation

• Matrix3D Compatibility - Matrix mathematics and compatibility layer
• Arena Pattern - Reliable 3D object management
• Transform System - Position, rotation, scale operations
• Pivot Usage Guide - Complete guide to pivot points and custom rotation anchors
• Pivot Implementation - Technical details of pivot system architecture

Debugging & Case Studies

• Parameter Reference Debugging Case Study - Real-world debugging session that led to framework improvements, enhanced error messages, and syntax clarification

🏗️ Architecture Highlights

Arena-Scene Bridge Pattern

// High-level object management (Arena)
var arena = Workspace.GetArena();
arena.AddShapeToStage<FoModel3D>(shape);

// Low-level rendering (Scene) - automatically bridged
var (found, scene) = arena.CurrentScene();
// Arena manages Scene connection

Unified Service Architecture

// Single service provides everything
[Inject] public IFoundryService FoundryService { get; set; } = null!;
[Inject] public IWorkspace Workspace { get; set; } = null!;

// Access sub-services
var arena = Workspace.GetArena();      // 3D object management
var drawing = Workspace.GetDrawing();  // 2D canvas management

Enhanced Animation System

shape.SetAnimationUpdate((self, tick, fps) =>
{
    // Any animation logic
    var pos = self.Transform.MoveBy(deltaX, deltaY, deltaZ);
    self.Transform.RotateBy(0, rotationSpeed, 0, AngleUnit.Radians);
    
    // Trigger re-render
    self.SetDirty(self.Transform.IsDirty);
});

🔄 Migration from Legacy Libraries

Before (Multiple Libraries)

// OLD - Multiple packages and registrations
dotnet add package FoundryBlazor
dotnet add package BlazorThreeJS

builder.Services.AddFoundryBlazorServices(envConfig);
builder.Services.AddBlazorThreeJSServices(envConfig);

[Inject] public IFoundryBlazorService Foundry { get; set; }
[Inject] public IBlazorThreeJSService ThreeJS { get; set; }

After (Unified Library)

// NEW - Single package and registration
dotnet add package ApprenticeFoundryWorldsAndDrawings

builder.Services.AddFoundryWorldsAndDrawingsServices(envConfig);

[Inject] public IFoundryService FoundryService { get; set; }
[Inject] public IWorkspace Workspace { get; set; }

✅ Zero Breaking Changes - All existing functionality preserved!

🎮 Interactive Demo & Examples

Explore the complete reference implementation:

• CanvasRebirth Project - Full working examples with multiple pages
• Clock Page - Real-time animations with Arena pattern
• SpacialFrameTest - 3D geometry visualization and transforms
• Home Page - Basic 3D model loading and rendering

Latest Architecture Features (v24.4.0)

• Enhanced Arena-Scene Bridge - More reliable 3D object management
• Improved Transform System - Better matrix operations and pivot support
• Universal Pivot Support - All primitives and models support custom center of gravity
• Normalized Pivot Coordinates - Consistent (-1 to 1) coordinate system for all objects
• Unified Service Registration - Single AddFoundryWorldsAndDrawingsServices() call
• Better Error Handling - Enhanced debugging and error messages
• Performance Optimizations - Reduced memory usage and faster rendering
• TypeScript Integration - Improved JavaScript interop with better type safety

📋 Requirements

• .NET 9.0 or higher
• Blazor Server or WebAssembly
• Modern Browser with WebGL support
• C# 12.0 language features

🛠️ Troubleshooting

Models Not Loading

• ✅ Add app.UseStaticFiles() to Program.cs
• ✅ Place models in /wwwroot/storage/StaticFiles/
• ✅ Use GetReferenceTo(@"storage/StaticFiles/model.glb")

Animations Not Working

• ✅ Use Arena pattern: arena.AddShapeToStage<FoModel3D>(shape)
• ✅ Call SetDirty() in animation callbacks
• ✅ Establish Arena-Scene bridge in OnAfterRenderAsync

Service Injection Errors

• ✅ Update to unified registration: AddFoundryWorldsAndDrawingsServices()
• ✅ Update service interfaces: IFoundryService, IWorkspace
• ✅ Update using statements to FoundryWorldsAndDrawings.*

Pivot Point Issues

• ✅ Use normalized coordinates (-1 to 1): Pivot = new Vector3(0, -0.5, 0)
• ✅ Set pivot before positioning: Set Transform.Pivot then Transform.Position
• ✅ Remember pivot affects both rotation AND scaling operations
• ✅ For ground objects: Use Pivot = new Vector3(0, -0.5, 0) for bottom center
• ✅ For doors/hinges: Use edge pivots like Pivot = new Vector3(-0.5, 0, 0)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

� Deployment & NuGet Publishing

Building for Release

# Build in release configuration
dotnet build --configuration Release

# Create NuGet package
dotnet pack --configuration Release

NuGet Package Details

• Package ID: ApprenticeFoundryWorldsAndDrawings
• Current Version: 24.4.0
• Target Framework: .NET 9.0
• License: MIT
• Repository: GitHub - FoundryBlazor

Package Contents

• Library DLL: Core functionality with 2D/3D capabilities
• Static Web Assets: Automatically included at _content/ApprenticeFoundryWorldsAndDrawings/
• TypeScript Definitions: For JavaScript interop
• Documentation: README.md included in package

Publishing Philosophy

• Semantic Versioning: Major.Minor.Build format (e.g., 24.4.0)
• Release Configuration: All packages built in Release mode for optimization
• Automatic Generation: GeneratePackageOnBuild enabled for development
• NuGet Gallery: Published to nuget.org

Deployment Workflow

1. Build: dotnet build --configuration Release
2. Package: dotnet pack --configuration Release
3. Locate Package: Find .nupkg file in bin\Release\ directory
4. Upload: Manual upload to nuget.org via web interface
5. Verify: Test installation with dotnet add package ApprenticeFoundryWorldsAndDrawings

📁 Package Location: .\bin\Release\ApprenticeFoundryWorldsAndDrawings.<version>.nupkg

�💬 Support

• 📖 Documentation: See migration guides and architecture documentation
• 🐛 Issues: Submit issues on GitHub for bug reports and feature requests
• 💡 Examples: Reference the CanvasRebirth project for working implementations
• 🚀 Migration Help: Use the provided migration guide for upgrading from legacy libraries
• 📦 NuGet: ApprenticeFoundryWorldsAndDrawings Package

Ready to build amazing 2D/3D Blazor applications with FoundryWorldsAndDrawings! 🎉