This repository contains the code of the single page application (SPA) which serves as the frontend of ShapeDiver App Builder in a special version which uses iJewel3D. Read more about this integration here.
Note
You can find the latest deployed version of this code here:
- Anonymous access (used for embedding of App Builder): https://appbuilder.shapediver.com/v1/ijewel3d/latest/
- In-platform access (requires you to be logged in on the ShapeDiver platform): https://www.shapediver.com/app/builder/v1/ijewel3d/latest/
Click one of these links to see instructions on how to load your model.
Specific versions of the App Builder can be accessed by replacing latest with a version string.
Example:
ShapeDiver turns your Grasshopper files into online applications. Safely share your design tools with others without exposing the original code. Easily embed them on any website via an iframe or integrate them with your favorite eCommerce platform or ERP system via our APIs and SDKs. ShapeDiver allows you to manage and enable easy access to your entire library of Grasshopper files from a web browser.
Read about ShapeDiver App Builder in our help center. This repository contains the App Builder Open-Source SDK. Building this code results in the single page application that renders the skeleton consisting of containers, tabs, widgets, and elements as explained here.
Highlights of the App Builder SDK:
- Extensive support for styling using themes
- Easy to be extended by further types of widgets etc
- Great starting point for custom web apps using ShapeDiver and React
iJewel3D is a 3D jewelry design software tailored for the jewelry industry. It allows jewelers, designers, and manufacturers to create intricate, high-quality jewelry designs using advanced CAD (Computer-Aided Design) tools. The software is known for its robust features that facilitate the modeling, visualization, and customization of jewelry pieces in three dimensions.
ShapeDiver provides a multi-purpose 3D Viewer that offers extensive features for building interactive 3D configurators and web apps. For a complete overview of the ShapeDiver 3D Viewer, please refer to its documentation. Since the ShapeDiver 3D Viewer does not explicitly focus on rendering jewelry, and iJewel3D provides excellent results, we decided to provide this integration. Note that using iJewel3D with ShapeDiver requires a separate license. Please contact us for details.
The material definitions used by ShapeDiver and iJewel3D are similar but different. Material properties assigned to geometry using ShapeDiver's material components in Grasshopper can not be used to define iJewel3D materials directly. Therefore this integration uses the following approach to assign materials to objects by material name:
- Use the glTF 2.0 Material component to assign named materials to your geometric objects. Only the Name property of the material is important; all other properties are ignored.
- Use the glTF 2.0 Display component to output geometry.
The display component saves the geometry, including its material assignments, to a glTF file, which is exposed on the Geometry Backend API and loaded by the headless ShapeDiver 3D Viewer.
The updateCallback of the session assigns iJewel3D materials to geometric objects based on the names of the materials you assigned to the objects in Grasshopper. For each object, it does the following:
- Check if the object is assigned to a material. If not, iJewel3D renders the objects using a default material.
- Check if the object's material name is contained in the dynamic material database. If so, assign the material.
- Check if the object's material name is contained in the static material database. If so, assign the material.
You can create iJewel3D material definitions by using the iJewel3d playground. Use drag & drop to load a test model in format glTF or 3dm and edit the materials or assign new ones. Once you are done, export the material as a JSON by clicking on Download pmat (or Download dmat for gem stones) on the right-hand side of the UI while the object is selected. Copy your material definitions into one of the material databases and assign names to them.
The static material database allows to define materials statically, as part of the web application. You can find an example in staticMaterialDatabase.ts. The static material database is a dictionary mapping material names to iJewel3D material definitions.
Optionally you can define a dynamic material database using your Grasshopper model. An example can be found in this Grasshopper model: materials-json-test.ghx. The dynamic material database is a JSON dictionary mapping material names to iJewel3D material definitions.
iJewel3D offers caching and optimization possibilities that support rendering models using many gemstones. The caching happens by diamond material name. You can read more about this here. These are the most important takeaways:
- Use the same diamond material name for stones sharing the same geometry, even if they are placed in different locations of the scene.
- Use different material names for stones that are different from each other.
ShapeDiver's 3D Viewer offers features that are not yet available when using this integration. This includes the following features:
- Augmented reality
- Interactions (Selection, hovering, dragging)
- Attribute visualisation
- HTML anchor elements
These components are used to render the containers, tabs, widgets, and elements defined by the skeleton.
So far we have implemented two page templates. The template to be used can be configured using a property of the theme.
-
appshell(default): -
grid:- A simple grid layout without responsiveness.
- This template allows customization using the theme.
- Review the template code here.
The main page component serves as the root of all App Builder pages. It does this:
- Uses some custom hooks to resolve all the settings based on the query string.
- Opens a session with the ShapeDiver model to be used.
- Gets the JSON content of the data output called AppBuilder. This content represents the skeleton.
- Instantiates App Builder React components based on the skeleton.
- Uses the template selector to render the instantiated components using the selected page template.
- You can find the TypeScript type definition of the skeleton and the settings here. There are also validators for parsing these objects from JSON and validating them.
The useCustomTheme hook defines the default theme. Refer to the documentation of the Mantine theme object and the possibility to define default props for Mantine components to understand what can be customized (basically everything). The App Builder components make use of Mantine's useProps hook to plug into the theme, which means the behavior and styling of the App Builder components can be controlled by the theme as well.
There is no need to fork and adapt the code to customize the theme. You can store the theme properties in a settings file in JSON format, and instruct the App Builder SPA to use the settings from this file using the g query string parameter. Some examples:
- Default theme:
- https://appbuilder.shapediver.com/v1/main/latest/?slug=240425-perforationswall-4
(notice that there is no
gquery string parameter)
- https://appbuilder.shapediver.com/v1/main/latest/?slug=240425-perforationswall-4
(notice that there is no
- Custom theme 1:
- Custom theme 2:
Note that you can pass an absolute URL to the settings file when using the g query string parameter, i.e., you can host the settings file anywhere: https://appbuilder.shapediver.com/v1/main/latest/?slug=240425-perforationswall-4&g=https://appbuilder.shapediver.com/v1/main/latest/theme01.json
In a later release, we plan to implement a theme editor and to host the settings on the ShapeDiver platform.
The following query string parameters can be used to instruct the App Builder SPA which model to load:
See the following link for instructions on how to use this: https://www.shapediver.com/app/builder/v1/main/latest/
See the following link for instructions on how to use this: https://appbuilder.shapediver.com/v1/main/latest/
You can use a settings file in JSON format to specify which model to load. This supports referencing the model using slug or using a ticket and modelViewUrl. The settings file can also include theme properties as explained above. Example:
- Settings file: example02.json
- Using the settings file: https://appbuilder.shapediver.com/v1/main/latest/?g=example02.json
As mentioned above, you can pass an absolute URL to the settings file when using the g query string parameter, i.e., you can host the settings file anywhere.
Note that the slug (or ticket and modelViewUrl) defined directly in the settings file take precedence over the query string parameters.
Feel free to fork from this repository in case you want to develop and deploy your own flavour of the App Builder SPA.
In case you want to extend App Builder by new widgets, these are your options:
- Option 1:
- Fork this repository,
- extend the skeleton type definition and the skeleton validator by your new widget properties (look for
IAppBuilderWidget), and - implement them.
- Plug your new widgets into AppBuilderWidgetsComponent. Then
- build and deploy yourself, or
- submit a pull request to this repository.
- Option 2: Create an issue and tell us about the widgets you would like to be included.
- Option 3: Ask us on the forum.
Install dependencies:
npm i
Install submodule:
git submodule init
git submodule update
Start local development server:
npm run start
This runs the app in development mode. Open http://127.0.0.1:3000 to view it in the browser. The page will re-render when you make edits. You will also see potential errors in the console.
We recommend using an IDE like Visual Studio Code.
Recommended extensions:
The code works using node.js 18 and 20.
npm run build
Builds the app for production to the dist folder.
When developing using Chrome, the following browser extensions are useful:
- React Developer Tools
- Redux DevTools: allows to inspect the stores managed by zustand
To learn React, check out the React documentation.
This playlist contains some valuable tutorials about React, TypeScript, and Mantine.
The complete API documentation of the ShapeDiver 3D Viewer can be found here.
This example includes some tickets of ShapeDiver models for testing. You can author and upload your own Grasshopper models.
Apart from the App Builder functionality, this repository contains useful React components and hooks for using the ShapeDiver 3D Viewer and the ShapeDiver Platform Backend. If you want to develop a web application using React and ShapeDiver, this is a great codebase to start from.
In case you want to contribute to this repository, feel free to fork it and open pull requests.
This codebase is implemented using TypeScript. We use Vite as a build tool for fast development experience.
This codebase uses the Mantine UI Kit. However, the code has been developed having reusability in mind, which means it will easily be possible to swap out the UI Kit.
We use the zustand state manager to provide the following stores:
This store is used to manage viewports and sessions of the ShapeDiver 3D viewer.
Interface: IShapeDiverStoreSession, Implementation: useShapeDiverStoreSession
Interface: IShapeDiverStoreViewport, Implementation: useShapeDiverStoreViewport
Related hooks:
Related components:
- ViewportComponent makes use of useViewport
- ViewPage creates a single session using useSession and uses a ViewportComponent
This store provides a stateful abstraction of the parameter and export functionality offered by the ShapeDiver 3D Viewer.
Interface: IShapeDiverStoreParameters, Implementation: useShapeDiverStoreParameters
Related hooks:
- useSession
- useSessions
- useDefineGenericParameters
- useSessionPropsParameter
- useSessionPropsExport
- useParameter
- useExport
- useParameterComponentCommons
- useSortedParametersAndExports
- useParameterChanges
Related components:
- Parameter components Components for the most common parameter types supported by ShapeDiver, uses useParameterComponentCommons.
- ExportButtonComponent allows to trigger an export and makes use of useExport.
- ParametersAndExportsAccordionComponent implements an accordion of grouped parameter and export components.
This code is provided as is. We do not warrant it to be useful for any purpose.