ApprenticeFoundryBlazor 23.4.0

FoundryBlazor

A comprehensive C# / Blazor diagramming library that combines 2D and 3D visualization capabilities for developers.

Overview

FoundryBlazor is a powerful diagramming and visualization library that brings together the best features of Visio, Three.js, and CesiumJS into the Blazor ecosystem. Originally demonstrated at NDC Oslo 2023, it's now available as a NuGet package supporting both Blazor Server and WebAssembly applications.

Features

• 2D Diagramming: Complete shape library with advanced layout algorithms
• 3D Integration: Seamless 2D/3D visualization combining
• Glued Connections: Dynamic connections that maintain relationships during layout changes
• Multi-page Diagrams: Scaled diagrams across multiple pages
• Performance Optimized: Object pooling and efficient rendering
• Cross-platform: Works in both Blazor Server and WebAssembly

Installation

dotnet add package ApprenticeFoundryBlazor

Quick Start

1. Configure Services

Add FoundryBlazor services to your Program.cs:

using FoundryBlazor;

var builder = WebApplication.CreateBuilder(args);

// Add Blazor services
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor(); // For Blazor Server

// Add FoundryBlazor services
builder.Services.AddFoundryBlazorServices();

var app = builder.Build();

// Configure the HTTP request pipeline
app.UseStaticFiles(); // Essential for static assets
app.UseRouting();
app.MapBlazorHub();
app.MapFallbackToPage("/_Host");

app.Run();

2. Add Required Static Assets

Add these references to your _Host.cshtml (Blazor Server) or index.html (WebAssembly):

<link href="_content/ApprenticeFoundryBlazor/css/bootstrap/bootstrap.min.css" rel="stylesheet" />
<link href="_content/ApprenticeFoundryBlazor/css/site.css" rel="stylesheet" />
<link href="_content/Radzen.Blazor/css/material-base.css" rel="stylesheet" />


<script src="_content/Blazor.Extensions.Canvas/blazor.extensions.canvas.js"></script>
<script src="_content/ApprenticeFoundryBlazorThreeJS/js/blazor-three-js.js"></script>
<script src="_content/ApprenticeFoundryBlazor/js/app-lib.js"></script>
<script src="_content/Radzen.Blazor/Radzen.Blazor.js"></script>

3. Using 2D Canvas Component

@page "/canvas2d-demo"
@using FoundryBlazor.Shared
@using FoundryBlazor.Shape
@inject IWorkspace Workspace

<h3>2D Canvas Diagramming</h3>

<div class="container-fluid">
 <div class="row">
 
 <div class="col-3">
 <div style="height: 600px; border: 1px solid #ccc;">
 <ShapeTreeView />
 </div>
 </div>
 
 
 <div class="col-9">
 <Canvas2DComponent SceneName="MainCanvas2D"
 CanvasWidth="1200" 
 CanvasHeight="600"
 WithAnimations="true" />
 </div>
 </div>
</div>

<div class="mt-3">
 <button class="btn btn-primary" @onclick="AddRectangle">Add Rectangle</button>
 <button class="btn btn-success" @onclick="AddCircle">Add Circle</button>
 <button class="btn btn-warning" @onclick="ClearCanvas">Clear Canvas</button>
</div>

@code {
 protected override async Task OnInitializedAsync()
 {
 // Initialize with some default shapes
 var drawing = Workspace.GetDrawing();
 
 // Add a rectangle
 var rect = new FoShape2D("Rectangle1", 120, 80, "Blue");
 rect.PinX = 200;
 rect.PinY = 150;
 drawing?.AddShape(rect);
 
 // Add a circle (using rectangle with equal width/height for simplicity)
 var circle = new FoShape2D("Circle1", 100, 100, "Red");
 circle.PinX = 400;
 circle.PinY = 200;
 drawing?.AddShape(circle);
 
 await base.OnInitializedAsync();
 }
 
 private void AddRectangle()
 {
 var drawing = Workspace.GetDrawing();
 var random = new Random();
 
 var rect = new FoShape2D($"Rectangle_{DateTime.Now.Ticks}", 
 80 + random.Next(40), 
 60 + random.Next(40), 
 "Green");
 rect.PinX = 100 + random.Next(800);
 rect.PinY = 100 + random.Next(400);
 
 drawing?.AddShape(rect);
 StateHasChanged();
 }
 
 private void AddCircle()
 {
 var drawing = Workspace.GetDrawing();
 var random = new Random();
 var size = 60 + random.Next(40);
 
 var circle = new FoShape2D($"Circle_{DateTime.Now.Ticks}", size, size, "Orange");
 circle.PinX = 100 + random.Next(800);
 circle.PinY = 100 + random.Next(400);
 
 drawing?.AddShape(circle);
 StateHasChanged();
 }
 
 private void ClearCanvas()
 {
 var drawing = Workspace.GetDrawing();
 drawing?.ClearAll();
 StateHasChanged();
 }
}

4. Using 3D Canvas Component

@page "/canvas3d-demo"
@using FoundryBlazor.Shared
@using FoundryBlazor.Shape
@inject IWorkspace Workspace

<h3>3D Canvas Visualization</h3>

<div class="container-fluid">
 <div class="row">
 
 <div class="col-8">
 <Canvas3DComponent SceneName="MainCanvas3D"
 CanvasWidth="800"
 CanvasHeight="600"
 WithAnimations="true" />
 </div>
 
 
 <div class="col-4">
 <div class="card">
 <div class="card-header">
 <h5>3D Controls</h5>
 </div>
 <div class="card-body">
 <button class="btn btn-primary mb-2 w-100" @onclick="Add3DShape">Add 3D Shape</button>
 <button class="btn btn-success mb-2 w-100" @onclick="AnimateShapes">Animate Shapes</button>
 <button class="btn btn-warning mb-2 w-100" @onclick="ResetCamera">Reset Camera</button>
 <button class="btn btn-danger mb-2 w-100" @onclick="Clear3DScene">Clear Scene</button>
 
 <hr />
 
 <h6>Camera Controls:</h6>
 <p><small>
 • Left Mouse: Rotate<br/>
 • Right Mouse: Pan<br/>
 • Scroll: Zoom
 </small></p>
 </div>
 </div>
 </div>
 </div>
</div>

@code {
 private int shapeCounter = 0;
 
 protected override async Task OnInitializedAsync()
 {
 // Initialize 3D scene with some basic shapes
 var arena = Workspace.GetArena();
 
 // Add some initial 3D shapes programmatically
 // Note: Actual 3D shape creation depends on your 3D shape classes
 
 await base.OnInitializedAsync();
 }
 
 private void Add3DShape()
 {
 var arena = Workspace.GetArena();
 var random = new Random();
 
 // Example of adding 3D shapes (adjust based on your actual 3D shape classes)
 shapeCounter++;
 
 // This is conceptual - replace with actual 3D shape creation
 // var shape3D = new FoShape3D($"Shape3D_{shapeCounter}");
 // shape3D.Position = new Vector3(
 // random.Next(-5, 5), 
 // random.Next(-5, 5), 
 // random.Next(-5, 5)
 // );
 // arena?.AddShape(shape3D);
 
 StateHasChanged();
 }
 
 private void AnimateShapes()
 {
 // Trigger animations on 3D shapes
 // Implementation depends on your animation system
 StateHasChanged();
 }
 
 private void ResetCamera()
 {
 // Reset 3D camera to default position
 // Implementation depends on your camera system
 StateHasChanged();
 }
 
 private void Clear3DScene()
 {
 var arena = Workspace.GetArena();
 arena?.ClearAll();
 StateHasChanged();
 }
}

5. Combined 2D and 3D Canvas Example

@page "/combined-canvas"
@using FoundryBlazor.Shared
@using FoundryBlazor.Shape
@inject IWorkspace Workspace

<h3>Combined 2D & 3D Visualization</h3>

<div class="container-fluid">
 <div class="row">
 
 <div class="col-2">
 <div style="height: 500px;">
 <RadzenShapeTreeView />
 </div>
 </div>
 
 
 <div class="col-5">
 <h5>2D Diagram</h5>
 <Canvas2DComponent SceneName="Combined2D"
 CanvasWidth="500" 
 CanvasHeight="400"
 WithAnimations="true" />
 </div>
 
 
 <div class="col-5">
 <h5>3D Visualization</h5>
 <Canvas3DComponent SceneName="Combined3D"
 CanvasWidth="500"
 CanvasHeight="400"
 WithAnimations="true" />
 </div>
 </div>
 
 <div class="row mt-3">
 <div class="col-12">
 <button class="btn btn-primary me-2" @onclick="SyncViews">Sync 2D → 3D</button>
 <button class="btn btn-success me-2" @onclick="AddToBoth">Add to Both</button>
 <button class="btn btn-warning me-2" @onclick="ClearBoth">Clear Both</button>
 </div>
 </div>
</div>

@code {
 private void SyncViews()
 {
 // Example: Convert 2D shapes to 3D representation
 var drawing = Workspace.GetDrawing();
 var arena = Workspace.GetArena();
 
 // Implementation would depend on your specific shape conversion logic
 // This demonstrates the concept of syncing between 2D and 3D
 
 StateHasChanged();
 }
 
 private void AddToBoth()
 {
 var drawing = Workspace.GetDrawing();
 var arena = Workspace.GetArena();
 var random = new Random();
 
 // Add to 2D
 var rect2D = new FoShape2D($"Synced2D_{DateTime.Now.Ticks}", 100, 60, "Purple");
 rect2D.PinX = 100 + random.Next(300);
 rect2D.PinY = 100 + random.Next(200);
 drawing?.AddShape(rect2D);
 
 // Add corresponding 3D shape
 // var shape3D = new FoShape3D($"Synced3D_{DateTime.Now.Ticks}");
 // arena?.AddShape(shape3D);
 
 StateHasChanged();
 }
 
 private void ClearBoth()
 {
 Workspace.GetDrawing()?.ClearAll();
 Workspace.GetArena()?.ClearAll();
 StateHasChanged();
 }
}

Advanced Features

Event Handling and Inter-Component Communication

@using BlazorComponentBus
@using FoundryBlazor.PubSub
@inject ComponentBus PubSub
@implements IDisposable

<Canvas2DComponent SceneName="EventCanvas" />

@code {
 protected override async Task OnInitializedAsync()
 {
 // Subscribe to shape selection events
 PubSub.SubscribeTo<ShapeUIEvent>(OnShapeSelected);
 
 // Subscribe to refresh events
 PubSub.SubscribeTo<RefreshUIEvent>(OnUIRefresh);
 
 await base.OnInitializedAsync();
 }
 
 private async Task OnShapeSelected(ShapeUIEvent eventArgs)
 {
 Console.WriteLine($"Shape selected: {eventArgs.Shape?.Name}");
 // Handle shape selection logic
 StateHasChanged();
 }
 
 private async Task OnUIRefresh(RefreshUIEvent eventArgs)
 {
 // Handle UI refresh
 StateHasChanged();
 }
 
 public void Dispose()
 {
 PubSub?.UnSubscribeFrom<ShapeUIEvent>(OnShapeSelected);
 PubSub?.UnSubscribeFrom<RefreshUIEvent>(OnUIRefresh);
 }
}

Custom Shape Creation

// Create custom 2D shapes
public class CustomShape : FoShape2D
{
 public CustomShape(string name) : base(name, "CustomColor")
 {
 // Custom initialization
 Width = 150;
 Height = 100;
 }
 
 // Override drawing behavior if needed
 // Custom rendering logic can be implemented here
}

// Usage in component
private void AddCustomShape()
{
 var drawing = Workspace.GetDrawing();
 var customShape = new CustomShape("MyCustomShape");
 customShape.PinX = 300;
 customShape.PinY = 200;
 drawing?.AddShape(customShape);
}

Performance Optimization

// For large datasets, disable animations
<Canvas2DComponent SceneName="LargeDataset"
 CanvasWidth="1200" 
 CanvasHeight="800"
 WithAnimations="false" />

// Batch operations for better performance
private void AddMultipleShapes()
{
 var drawing = Workspace.GetDrawing();
 
 // Batch add multiple shapes
 for (int i = 0; i < 100; i++)
 {
 var shape = new FoShape2D($"BatchShape_{i}", 50, 30, "Blue");
 shape.PinX = (i % 10) * 60 + 50;
 shape.PinY = (i / 10) * 40 + 50;
 drawing?.AddShape(shape);
 }
 
 // Trigger single refresh instead of multiple
 StateHasChanged();
}

Troubleshooting

Common Issues

Canvas not rendering:

• Ensure all required JavaScript files are loaded in the correct order
• Verify app.UseStaticFiles() is called in Program.cs
• Check browser console for JavaScript errors

Services not found:

Unable to resolve service for type 'FoundryBlazor.IWorkspace'

Solution: Add services.AddFoundryBlazorServices() to Program.cs

Static assets not loading:

• Verify the _content/ApprenticeFoundryBlazor/ path is accessible
• Check that static files middleware is properly configured
• Ensure NuGet package is properly restored

Browser Compatibility

• Recommended: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
• Canvas2D: Supported by all modern browsers
• WebGL (3D): Required for 3D components, supported by 97%+ of browsers

Demo & Examples

Visit our interactive demo: https://apprenticefoundry.github.io/

Architecture Documentation

Matrix3D Compatibility System

FoundryBlazor uses a compatibility wrapper architecture for 3D matrix operations:

• - Complete technical documentation of the Matrix3D wrapper pattern that delegates to BlazorThreeJS.Matrix3 while maintaining API compatibility

Key Features

• Delegation Pattern: Matrix3D serves as a compatibility bridge to BlazorThreeJS mathematics
• Type Conversion: Seamless bridging between FoVector3D (double precision) and Vector3 (float precision)
• Object Pooling: Performance optimization through matrix instance reuse
• Zero Breaking Changes: Existing code works unchanged while benefiting from enhanced math

Related Projects

• BlazorThreeJS: Provides the core mathematical foundation for 3D operations
• Three2025: Application project demonstrating integrated 3D capabilities

Package Information

• Package Name: ApprenticeFoundryBlazor
• Current Version: 23.3.0
• Target Framework: .NET 9.0
• Compatible With: Blazer Server and WebAssembly

Requirements

• .NET 9.0 or higher
• Blazor Server or WebAssembly
• Modern web browser with Canvas2D and WebGL support

License

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

Contributing

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

Support

• Demo: https://apprenticefoundry.github.io/
• Issues: Submit issues on GitHub for bug reports and feature requests
• Documentation: See the Matrix3D compatibility documentation for technical details