3D graphics for blazor applications
$ dotnet add package ApprenticeFoundryBlazorThreeJSBlazorThreeJS is a NuGet package that provides seamless integration of the Three.js library with Blazor applications. This package allows developers to create rich 3D graphics and animations using the power of Three.js within a Blazor project.
To install BlazorThreeJS, run the following command in the NuGet Package Manager Console:
Install-Package ApprenticeFoundryBlazorThreeJS
Alternatively, you can add the package reference directly to your .csproj file:
<PackageReference Include="ApprenticeFoundryBlazorThreeJS" Version="23.1.0" />
Unlike standard Three.js, BlazorThreeJS allows you to rotate objects around any point:
// Rotate a building around its base (bottom center)
Transform = new Transform3("Building") {
Position = new Vector3(0, 0, 0), // Ground position
Pivot = new Vector3(0, -1, 0), // Rotate around bottom
Rotation = new Euler(0, 45°, 0) // 45° turn on foundation
}
Add the BlazorThreeJS package to your Blazor project using the installation instructions above.
In your Blazor app's _Host.cshtml, _Layout.cshtml, or App.razor, add the required JavaScript reference:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>My Blazor App</title>
<base href="~/" />
<!-- Optional: BlazorThreeJS styles -->
<link href="_content/ApprenticeFoundryBlazorThreeJS/css/blazor-threejs.css" rel="stylesheet" />
</head>
<body>
<!-- Your app content -->
<!-- Required: BlazorThreeJS JavaScript -->
<script src="_content/ApprenticeFoundryBlazorThreeJS/dist/app-lib.js"></script>
<!-- Blazor framework script -->
<script src="_framework/blazor.server.js"></script>
</body>
</html>
@page "/3d-scene"
@using BlazorThreeJS.Viewers
@using BlazorThreeJS.Core
@using BlazorThreeJS.Maths
<ViewerThreeD @ref="viewer"
Width="800"
Height="600"
SceneName="MyScene" />
@code {
private ViewerThreeD? viewer;
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (firstRender && viewer != null)
{
await CreateScene();
}
}
private async Task CreateScene()
{
// Create a box that rotates around its bottom face
var box = new Mesh3D("FloorBox")
{
Transform = new Transform3("FloorBox")
{
Position = new Vector3(0, 0, 0), // Position on floor
Pivot = new Vector3(0, -1, 0), // Rotate around bottom
Rotation = new Euler(0, 45 * Math.PI/180, 0), // 45° rotation
Scale = Vector3.One
},
// Add geometry and material...
};
await viewer.AddObjectToScene(box);
}
}
One of the most powerful new features is the ability to set custom pivot points for object rotation:
// Perfect for placing objects on the ground
var box = new Mesh3D("FloorBox")
{
Transform = new Transform3("FloorBox")
{
Position = new Vector3(0, 0, 0), // Floor position
Pivot = new Vector3(0, -1, 0), // Rotate around bottom face
// Now rotations happen around the bottom edge, not center
}
};
// Rotate around bottom-left-front corner
var box = new Mesh3D("CornerBox")
{
Transform = new Transform3("CornerBox")
{
Position = new Vector3(0, 0, 0),
Pivot = new Vector3(-1, -2, -3), // Corner offset
Rotation = new Euler(0, 90 * Math.PI/180, 0) // 90° Y rotation
}
};
// Rotate around a point above the object
var mesh = new Mesh3D("HighPivot")
{
Transform = new Transform3("HighPivot")
{
Position = new Vector3(0, 5, 0), // Pivot point location
Pivot = new Vector3(0, -5, 0), // Object offset from pivot
// Object appears at (0,0,0) but rotates around (0,5,0)
}
};
Objects with pivot (0,0,0) work exactly as before - no changes needed to existing code!
BlazorThreeJS features a sophisticated architecture:
Object3D, Transform3, Mesh3D, etc.The Transform3 class provides robust transformation capabilities:
public class Transform3
{
public Vector3 Position { get; set; } // World position
public Vector3 Pivot { get; set; } // Custom rotation center (NEW!)
public Euler Rotation { get; set; } // Euler angle rotation
public Quaternion QuaternionRotation { get; set; } // Alternative rotation
public Vector3 Scale { get; set; } // Scale factors
// Automatic matrix caching with dirty flag optimization
public Matrix3 ToMatrix3() { /* Cached calculation */ }
}
Current Version: 23.1.0
Target Framework: .NET 9.0
License: MIT
Repository: https://github.com/ApprenticeFoundry/BlazorThreeJS
This NuGet package includes:
app-lib.js - 751KB)Make sure you've added the JavaScript reference to your app:
<script src="_content/ApprenticeFoundryBlazorThreeJS/dist/app-lib.js"></script>
Add the using statement to your component or _Imports.razor:
@using BlazorThreeJS.Viewers
@using BlazorThreeJS.Core
This project is licensed under the MIT License. See the LICENSE file for more details.