Skip to content

Latest commit

 

History

History
284 lines (211 loc) · 9.37 KB

readme.md

File metadata and controls

284 lines (211 loc) · 9.37 KB
Raw

Babylon.Blazor

Build status Publish Status NuGet Status

This library packages the well-known 3D library Babylon.js into a Razor component that can be used in a C# Blazor project. The library is intended to use for creation of molecules visualization and used limited API of Babylon library.
It is possible to compare different types of hosting models:

Pubchem Viewer - Demo application using library reference. Show chemical information from pubchem.ncbi.nlm.nih.gov

Getting Started

You can find the old version (.NET 5.0 and 6.0 compatible) on the branch net50 New version supports .NET 8.0 and I use Blazor Web App template with server prerendring for demo purposes.

Prerequisites

To create Blazor Apps, install the latest version of Visual Studio with the ASP.NET and web development workload. For using .Net 8.0 you need at least Visual Studio 2022 17.8+. Another alternative would be to use Visual Studio code. Click here for more information.

Library used IJSObjectReference

Installing

After you have created your Blazor project, you need to do the following steps:

Install the latest NuGet Package

Using Package Manager

Install-Package Babylon.Blazor

Using .NET CLI

dotnet add package Babylon.Blazor

Using MS VS Manage NuGet Packages search for Babylon.Blazor

Add reference to babylon js library. Add 2 lines (with babylonjs) into app.razor/index.html You will also need to add a reference to babylonInterop.js.

<body>
    <Routes />
    <script src="https://preview.babylonjs.com/babylon.js"></script>
    <script src="https://preview.babylonjs.com/loaders/babylonjs.loaders.min.js"></script>
    <script type="module" src="_content/Babylon.Blazor/babylonInterop.js"></script>
    <script src="_framework/blazor.web.js"></script>
</body>

Add InstanceCreator to DI Server Part

 public class Program
    {
        public static async Task Main(string[] args)
        {
       ...
           builder.Services.AddTransient<InstanceCreatorBase>(sp => new InstanceCreatorAsyncMode(sp.GetService<IJSRuntime>()));
           var app = builder.Build(); 
        }
    }

Note Server side support only IJSObjectReference

Client Part

builder.Services.AddTransient<InstanceCreatorBase>(sp => new InstanceCreator(sp.GetService<IJSRuntime>()));

await builder.Build().RunAsync();

Add Razor page and replace context to similar code

@page "/test"
@using Babylon.Blazor.Chemical
@rendermode InteractiveAuto
<h1>Water</h1>

<p> Chemical formula of water is H<sub>2</sub>O</p>

<div style="height: 600px;">
   <BabylonCanvas CanvasId="Canvas1" SceneData=@PanelData/>
</div>

@code {

    ChemicalData PanelData { get; } = new ChemicalData();

    async Task InitDataAsync()
    {
        // Fake await line
        await Task.FromResult(1);


        PanelData.Atoms.Add(new AtomDescription() { Name = "O", X = 2.5369, Y = -0.1550, Z = 0.0000 });
        PanelData.Atoms.Add(new AtomDescription() { Name = "H", X = 3.0739, Y =  0.1550, Z = 0.0000 });
        PanelData.Atoms.Add(new AtomDescription() { Name = "H", X = 2.0000, Y =  0.1550, Z = 0.0000 });

        PanelData.Bonds.Add(new BondDescription(1, 2,  BondDescription.BondType.Single));
        PanelData.Bonds.Add(new BondDescription(1, 3, BondDescription.BondType.Single));
    }

    protected override async Task OnInitializedAsync()
    {
        await InitDataAsync();
    }

}

Add to _Imports.razor

@using Babylon.Blazor

NOTE: You can skip this step

Demo Application

For demo application I implemented: Water, Benzene, Epinephrine and Sprite example. All descriptions was get from PubChem catalog. As I not found atom size into description - I not set it. The same is for double and triple bonds - the parallel lines rotation vector mostly oriented along the Y axis. Colors selected automatically from color palette. If chemist sees something wrong then please tell me. My goal was to create a C# interface to a Java Script library. Not to draw molecules absolutely correctly.

Water H2O

--water pic--

Benzene C6H6

--Benzene pic--

Epinephrine C9H13NO3

--Epinephrine pic--

In addition, I draw some tests

Test1 (not used anymore)

--Test1 pic--

Test2
--Test2 pic--

How it works?

With .NET 5.0 and above, it is very easy to transfer objects between Java Script and C#. Calling functions from a JS object in C# is also easy.

You can read more in article Using JS Object References in Blazor WASM to wrap JS libraries

Here is the steps you need to wrap JS library for Blazor Web Assembly application:

  1. Create Razor library with LibraryName.
  2. Create under wwwroot js export file with functions like this:
export function functionName(parameters) {
        ...
        return javaObject;
}
  1. Create library wrapper
IJSInProcessObjectReference libraryWrapper = await _jSInstance.InvokeAsync<IJSInProcessObjectReference>("import",
                                                             "./_content/LibraryName/LibraryJSExport.js");

NOTE: You can get _jSInstance into main application over dependency injection or service provider call

  1. Create C# wrapper
public async Task<CsharpObj> CsFunctionName(int parameter)
{
        var jsObjRef = await _libraryWrapper.InvokeAsync<IJSObjectReference>("jsFunctionName", parameter);
        return new CsharpObj(jsObjRef);
}
  1. Call the wrapped function
var CsharpObj = await LibraryWrapper.CsFunctionName(2);

NOTE: you can use JS object as function parameter. Use jsObjRef for it.

How to create custom scene?

If you don't want to draw molecules then it is possible to create your own component

  1. Create your own creator class
public class MySceneCreator : SceneCreator
{
    public override async Task CreateAsync(BabylonCanvasBase canvas)
    {
    ...
    }
}
  1. Create Data class
public class MyCustomData:IData
{

}
  1. Create new canvas
public class MyCustomCanvas : BabylonCanvasBase
{
       protected virtual async Task InitializeSzene(LibraryWrapper LibraryWrapper, string canvasId)
        {
            MyCustomData panelData;
            if (ChemicalData is MyCustomData)
            {
                panelData = (MyCustomData)SceneData;
	            MySceneCreator creator = new MySceneCreator(LibraryWrapper, canvasId, panelData);
    	        await creator.CreateAsync(this);
            }
        }
}
  1. Create new Rasor component
@inherits MyCustomCanvas
<canvas id=@CanvasId touch-action="none" />

What's New

in Version 1.5

  • update to .NET 9.0

in Version 1.4

  • update to .NET 8.0
  • added show loading component. Currently we use server-side prerendering, but the babylog engine could only work client-side. The Babylon engine takes some time to render. We want to show the user a 'loading' notification instead of an empty area. The default text is "Loading...". You can change it to something else using 'LoadingTemplate'
<BabylonCanvas CanvasId="Canvas1" SceneData=@PanelData>
   <LoadingTemplate>
       <div>Loading Custom Demo...</div>
   </LoadingTemplate>
</BabylonCanvas>

in Version 1.3

  • added sprite manager
  • added sprite with base attributes
  • added callback function sample JS to .NET
  • added sprite sample
    --Sprite sample pic--

in Version 1.2

  • added single color Box
  • added Torus
  • added sample of custom scene drawing
    --Custom Draw pic--

in Version 1.1

New features:

  • Show errors on 3D canvas
  • Added new component ChemFormulaViewer
  • Expand ChemicalData. Added new properties: ErrorText, MolecularFormula, Name, ShowErrorText

##Developer notes

If you want to change the library then don't use IIS express by debugging because JS files will be not easy to change.

In some cases, you can try to refresh the page from developer mode with the cache disabled.

--Sprite sample pic--