--- language: "en" --- # ShapeDiver Help Center ## ShapeDiver Help Center New to ShapeDiver? Check out our Get Started pages for Designers and Developers! Scroll further below for thematic articles. [Get help from our team!](https://help.shapediver.com/doc/community-and-support.md) ### Release notes * #### [Platform - Release Notes](https://help.shapediver.com/doc/platform-release-notes-1.md) March 11, 2022 * #### [Plugin - Release Notes](https://help.shapediver.com/doc/plugin-release-notes-1.md) March 11, 2022 * #### [App Builder - Release Notes](https://help.shapediver.com/doc/app-builder-release-notes.md) June 02, 2025 ### Get Started * #### [What is ShapeDiver?](https://help.shapediver.com/doc/what-is-shapediver.md) A general introduction to ShapeDiver. Start here if you are not familiar yet with parametric design and how ShapeDiver leverages it for various applications in the product design and AEC industries. * #### [Designers](https://help.shapediver.com/doc/get-started-grasshopper-designers.md) Whether you are completely new to Rhino \& Grasshopper or already have some experience, in this section we explain how to get your first parametric CAD files uploaded to ShapeDiver. * #### [Developers](https://help.shapediver.com/doc/get-started-developers.md) Understand how to work with ShapeDiver models created by designers. Learn about the various ways to interact with them using our APIs and SDKs. ### Documentation * #### [Online Platform](https://help.shapediver.com/doc/online-platform.md) * [Uploading models](https://help.shapediver.com/doc/uploading-models.md) * [Editing models](https://help.shapediver.com/doc/editing-models.md) * [Interacting with models](https://help.shapediver.com/doc/interacting-with-models.md) * [Model library](https://help.shapediver.com/doc/model-library.md) * [Account analytics](https://help.shapediver.com/doc/account-analytics.md) * [4 more pages](https://help.shapediver.com/doc/online-platform.md) * #### [Grasshopper](https://help.shapediver.com/doc/grasshopper.md) * [Building ShapeDiver Models](https://help.shapediver.com/doc/building-shapediver-models.md) * [ShapeDiver plugin for Grasshopper](https://help.shapediver.com/doc/shapediver-plugin-for-grasshopper.md) * [Tutorial definitions](https://help.shapediver.com/doc/tutorial-definitions.md) * [FAQ](https://help.shapediver.com/doc/faq.md) * #### [ShapeDiver App Builder](https://help.shapediver.com/doc/shapediver-app-builder.md) * [Build Apps in Grasshopper](https://help.shapediver.com/doc/build-apps-in-grasshopper.md) * [Explore Apps from the platform](https://help.shapediver.com/doc/explore-apps-from-the-platform.md) * [Embed Apps in external websites](https://help.shapediver.com/doc/embed-apps-in-external-websites.md) * [Customize a theme](https://help.shapediver.com/doc/customize-a-theme.md) * [App Builder Open-Source SDK](https://help.shapediver.com/doc/app-builder-open-source-sdk.md) * [2 more pages](https://help.shapediver.com/doc/shapediver-app-builder.md) * #### [Desktop Clients](https://help.shapediver.com/doc/shapediver-desktop-clients.md) * [The ShapeDiver Client Application](https://help.shapediver.com/doc/the-shapediver-client-application.md) * [Using Rhino as a Desktop Client](https://help.shapediver.com/doc/using-rhino-as-a-shapediver-client.md) * [Using Adobe Illustrator as a Desktop Client](https://help.shapediver.com/doc/using-adobe-illustrator-as-a-shapediver-client.md) * #### [Viewer](https://help.shapediver.com/doc/viewer.md) * [First Steps](https://help.shapediver.com/doc/first-steps.md) * [Core Concepts](https://help.shapediver.com/doc/core-concepts.md) * [Scene Appearance](https://help.shapediver.com/doc/scene-appearance.md) * [User Interaction](https://help.shapediver.com/doc/user-interaction.md) * [Advanced / Integration](https://help.shapediver.com/doc/advanced-integration.md) * [1 more pages](https://help.shapediver.com/doc/viewer.md) * #### [APIs and SDKs](https://help.shapediver.com/doc/apis-and-sdks.md) * [Geometry Backend](https://help.shapediver.com/doc/geometry-backend.md) * [Platform Backend](https://help.shapediver.com/doc/platform-backend.md) * [sdTF - Structured data transfer format](https://help.shapediver.com/doc/sdtf-structured-data-transfer-format.md) * #### [Security](https://help.shapediver.com/doc/security.md) * [Security - Overview](https://help.shapediver.com/doc/security-overview.md) * [Account Security](https://help.shapediver.com/doc/account-security.md) * #### [Integrations](https://help.shapediver.com/doc/integrations.md) * [ShapeDiver for Shopify](https://help.shapediver.com/doc/shapediver-for-shopify.md) * [ShapeDiver for Speckle](https://help.shapediver.com/doc/shapediver-for-speckle.md) * [ShapeDiver for Wordpress and WooCommerce](https://help.shapediver.com/doc/shapediver-for-wordpress-and-woocommerce.md) * [ShapeDiver for Autodesk Forma](https://help.shapediver.com/doc/shapediver-for-autodesk-forma.md) * [ShapeDiver for Viktor.ai](https://help.shapediver.com/doc/shapediver-for-viktor-ai.md) * [2 more pages](https://help.shapediver.com/doc/integrations.md) * #### [Guides and Tutorials](https://help.shapediver.com/doc/guides-and-tutorials.md) * [ShapeDiver \<-\> Rhino Compute](https://help.shapediver.com/doc/shapediver-rhino-compute.md) * [Rendering Guide: How to Make Your ShapeDiver Models Look Great](https://help.shapediver.com/doc/visualization-guide-how-to-make-your-models-look-r.md) * [Agent Skills](https://help.shapediver.com/doc/agent-skills.md) * #### [Pricing](https://help.shapediver.com/doc/pricing.md) * [Credits](https://help.shapediver.com/doc/credits.md) --- language: "en" --- # Access JSON After parsing a JSON string using the [Parse JSON](https://help.shapediver.com/doc/parse-json.md)component, the next step is to access the data via the *Access JSON* component. Using this component, you can search for the value associated with the input property, if it exists: ![image-20211227-164000.png](https://help.shapediver.com/__attachments/a_7468b20afabeaba6ce8e74b26d1c7d84e92918decd87b1aec79adcabbf844c68/image-20211227-164000.png?cb=7d75dee6510cac4b4441e976838a291b) Additionally, you can provide a index number if the attribute you want to access contains an array of values: ![image-20211227-164136.png](https://help.shapediver.com/__attachments/a_646a63c8a87e4392c8030999252c58e82382b177e00137ac2335fb0eb7318ae7/image-20211227-164136.png?cb=9a5624e43c0d95cd29d4cb9ebfe116c6) If you have an **array of JSON objects** which have the same attribute name you are looking for, you will get back **a tree in which each branch reference back to each object.** ![image-20211227-164825.png](https://help.shapediver.com/__attachments/a_7b88e50da3be616404b7da4c8f7d48853fb0a35003c287010eb7e98b1368b11c/image-20211227-164825.png?cb=4d34ccd08972f63e1a205450e845c5bf) --- language: "en" --- # Access Key Use the *Access Key* component to look for the value associated with a specific key contained in an existing Attributes object, if the key exists. ![image-20211229-122807.png](https://help.shapediver.com/__attachments/a_7862d29668c38cff1360ee667aa0de59a300857f6a4d96445613983f9450a43c/image-20211229-122807.png?cb=986f7d8facfff9aecafd5a09e15adb83) --- language: "en" --- # Account analytics Take me to my [account analytics](https://www.shapediver.com/app/analytics). Related documentation on our pricing system and how credits are charged: [Credits](https://help.shapediver.com/doc/credits.md) Browse to the "Analytics" tab in your dashboard to get detailed analytics about how visitors interact with your models. Several charts include fine-grained data about various metrics associated with your models. ![image-20260908-094513.png](https://help.shapediver.com/__attachments/a_c68c4dff9a7ca7191a5fc3c8e7d1f0d13c148b64553c23b540d4b6b516961d12/image-20260908-094513.png?cb=50730188eed975a785d537b672e59f9c) ## Filters ### Source filters The filters on the top left of the table correspond to source filters. They refer to the context in which each action displayed in the table was triggered. There are four contexts: * *Browser*: the actions were triggered by a user interacting with a model from a web browser, likely in the ShapeDiver platform, a ShapeDiver App, or embedded versions thereof. * *APIs*: the actions were triggered programmatically through one of the ShapeDiver APIs. * *Model loading*: specific credits are counted every time a Grasshopper definition needs to be loaded on one of the servers of the system it was uploaded to. This filter only applies to the "Model loading" category of the chart. * *AR*: one credit is spent each time a model is viewed in AR. This filter only applies to the "AR Requests" category of the chart. ### Model filter By default, the charts display the data aggregated for all models of the account. Use the "Model filter" button to pick a specific model for which you would like to explore analytics. ### Time filter Various preset time ranges are available, as well as custom ranges between two specified days. ## General metrics This chart provides detailed information about audience metrics related to actions taken by users interacting with the models of your account. Some of these actions trigger the spending of ShapeDiver [credits](https://help.shapediver.com/doc/credits.md). As a consequence, for each metric, we display both the total number of actions and the number of credits associated with those actions. We detail below each metric displayed in the table. ### Metrics * **Total credits** * *Sessions* are charged in 10-minute chunks. Opening a new session always starts one 10-minute chunk. If the session continues after the first chunk, our servers look for additional requests coming in. Once the first request outside the initial 10-minute chunk comes in, another chunk is started. This means that a browser tab that remains idle for hours because a user did not close it will not create additional credit charges until the user engages with it again. * *Computations* **:** Whenever data unavailable in our cache is requested, the necessary parameters are dispatched to one of our geometry workers to compute it. This worker will then run this computation and store all requested data in our cache. Once this is done, we answer the request as quickly as possible. The amount of time our workers require to complete this task is called *computation time*. It includes the time used by Grasshopper's solver and the time to read the results from Grasshopper and serialize them into files. * *Output Requests*: This type of request asks our servers to return the outputs of a ShapeDiver model for a specific set of parameters. Outputs are typically either geometry or materials used to display geometric objects in a viewer and attributes and meta-data of a limited size. Output Requests will be answered from our cache if the particular result has already been computed before, and they will trigger a computation on our geometry workers if this is not the case. * *Export Requests* **:** These requests call for the return of a specific export defined in a ShapeDiver model. Exports can be everything from CAD files to images, PDFs, or binary data. As for Output Requests, a computation will be triggered if the requested content is not available in our cache. * *Combined Requests* **:** In some situations, requesting outputs and exports for a set of parameters is more efficient through a single call. A Combined Request is an Output Request that also identifies one or several exports that should be computed and returned. * *Model Loading* **:** To deliver fast responses to your requests, we keep ShapeDiver models loaded on a number of geometry workers in parallel. We decide the number of workers on which a particular model remains loaded based on demand patterns, your type of plan, and several other considerations. This means that we have to open and load models from time to time on workers when we expect increased traffic for those particular models. Loading time includes opening the Grasshopper model, parsing it as far as this is necessary, and precompiling scripts. For some models, especially when they contain large numbers of components or many scripts, this process takes longer than to compute a solution. * *AR Requests* **:** The ShapeDiver platform and APIs allow you to download the 3D outputs of a ShapeDiver model as an asset for use in the native AR viewers of various mobile devices. ## Computation duration metrics This chart provides information about the duration of computations over the models associated with your account. It currently includes two different metrics: * *Total computation duration*: the accumulated computation time over the given time unit. * *Average computation duration*: the average computation time per request over the given time unit. --- language: "en" --- # Account Security ## Sharing Account Credentials on ShapeDiver At ShapeDiver, safeguarding your account and maintaining the integrity of our platform are top priorities. For this reason, sharing account credentials is not permitted. This policy protects both your data and our system's security while ensuring compliance with our agreements. ### Why is Sharing Credentials Not Allowed? Sharing your ShapeDiver account credentials with others violates several key provisions of our terms: * The [**Acceptable Use Policy**](https://a.storyblok.com/f/92524/x/062eec1c28/220401_shapediver_acceptable_use_policy.pdf) explicitly prohibits sharing, transferring, or providing access to an account designated for you to another person (§ 3.2)​. * The [**Customer Terms of Service**](https://a.storyblok.com/f/92524/x/328c949229/220401_shapediver_customer_terms_of_service.pdf) require customers and authorized users to keep all login credentials secure and confidential (§ 3.2(b))​. Additionally, sharing credentials puts both customers and the platform at risk. Unauthorized account sharing may be considered a crime in many jurisdictions, including [the US](https://www.nacdl.org/Landing/ComputerFraudandAbuseAct) and [the UK](https://www.bbc.com/news/technology-64003237). Enforcing this rule protects you from potential legal and security issues. It also reduces the risk of **account takeover fraud (ATO)**, where bad actors exploit shared or weak credentials to gain access to accounts and compromise sensitive information. Lastly, maintaining individual accounts ensures that every customer pays their fair share. This allows us to keep service prices reasonable while continuing to invest in innovative features and platform improvements. ### What Happens if Credentials are Shared? If we detect that credentials are being shared, we will follow these steps: 1. **Contact the User**: We will reach out to the account holder to address the issue, remind them of the terms, and discuss alternatives. 2. **Offer Alternatives**: We'll present secure and compliant options, such as upgrading the account to include multiple seats or purchasing additional seats via add-ons. 3. **Take Action if Necessary**: If the issue persists, we reserve the right to suspend or block the account as permitted under the Customer Terms of Service (§ 13.2(b))​. ### Better Ways to Collaborate We understand that teams often need to collaborate, and ShapeDiver offers various ways to share access to models securely. These include: * **Multi-Seat Plans**: Upgrade to a subscription plan designed for teams, where each user has their own credentials. * **Add Seats**: Expand your account with add-ons to provide individual access for more team members. * **Model Sharing Options**: Use built-in platform features to share models between individual accounts without compromising credentials. These alternatives enable seamless collaboration while ensuring the security and compliance of every user. ### Why Compliance Matters Beyond security, compliance with this policy is essential for the entire ShapeDiver community. By adhering to our terms, you contribute to a fair ecosystem where resources are distributed equitably. This fairness helps us keep costs manageable for everyone and allows us to continue delivering exceptional service and innovative tools. If you have any questions or need assistance selecting the right plan for your team, please [contact us](mailto:contact@shapediver.com). We're here to help! --- language: "en" --- # Action Components Actions are specific App Builder events that can be triggered in an App, either directly by clicking on a button (using an [Action Control](https://help.shapediver.com/doc/action-control.md) component) or along with specific events in the App (upcoming feature). * [Add to Cart Action](https://help.shapediver.com/doc/add-to-cart-action.md) * [Close Configurator Action](https://help.shapediver.com/doc/close-configurator-action.md) * [Create Model State Action](https://help.shapediver.com/doc/create-model-state-action.md) * [Set Browser Location Action](https://help.shapediver.com/doc/set-browser-location-action.md) * [Set Parameter Values Action](https://help.shapediver.com/doc/set-parameter-values.md) * [Parameter Value](https://help.shapediver.com/doc/parameter-value.md) --- language: "en" --- # Action Control ## Overview The *Action Control* component creates action buttons in an App built with the [App Builder](https://help.shapediver.com/doc/app-builder.md) components. Each button links to a specific action. You can customize the button with a label, icon, and tooltip. The component takes an Action as input, created by one of the [Action components](https://help.shapediver.com/doc/action-components.md) of the plugin. You can then include the created control in a [Controls Widget](https://help.shapediver.com/doc/controls-widget.md) within the App. ## First example Download an example definition [here](https://shapediver.github.io/GrasshopperExampleModels/11-AppBuilder/11F-ActionControl.ghx). The example below starts with a simple box that has two inputs: height and color. ![image-20250924-094823.png](https://help.shapediver.com/__attachments/a_622dc9f2c5399e9873552886f1bcb2c3724fd8dfc99c7dfb12db2dce481081ec/image-20250924-094823.png?cb=d9850cb9e98bcf2f7c41cb8edc1563da) Using the App Builder components, create an [App](https://help.shapediver.com/doc/build-app.md) with a single [Container](https://help.shapediver.com/doc/build-container.md) on the right. In this container, define one Controls Widget that includes two Action Controls. Both controls link to [*Set Parameter Values*](https://help.shapediver.com/doc/set-parameter-values.md) actions: * The first control, "Small and blue," sets the Height parameter to 2 and the Color parameter to Blue. * The second control, "Tall and green," sets the Height parameter to 8 and the Color parameter to Green. The created App looks like this: ![savedstatecreate.gif](https://help.shapediver.com/__attachments/a_44d3f42767da6e5981fe61b9dc4450869f50cb01dffd5775e74b6025b708df75/savedstatecreate.gif?cb=0a065933c0bd188b76f8e7ad4549933b) Read more about the [*Set Parameter Values*](https://help.shapediver.com/doc/set-parameter-values.md) action to learn more about this specific action. You can link multiple actions with Action Control components. --- language: "en" --- # Add Key-Value Pair Use the *Add Key-Value Pair* component to add one or several key-value pairs in an existing Attributes object. ![image-20211229-122330.png](https://help.shapediver.com/__attachments/a_5309ecc36e6b33713c35976d3400f2d6f12b5a00a012cc16b02efcb8cef3fbbd/image-20211229-122330.png?cb=ba0e1cf9db14c3c77170d8a2cf006803) Note that you can add any number of values simultaneously using the [Construct Attributes](https://help.shapediver.com/doc/construct-attributes.md) component, which supports lists of keys and values as inputs. --- language: "en" --- # Add to Cart Action The *Add to Cart Action* component creates an [++Action++](https://help.shapediver.com/doc/action-components.md) that creates a [++model state++](https://help.shapediver.com/doc/model-states-anonymous-saved-states.md) from the current state of the App, and creates a line item in the cart of an eCommerce store using that model state (see [ShapeDiver for Shopify](https://help.shapediver.com/doc/shapediver-for-shopify.md) or [ShapeDiver for WordPress/WooCommerce](https://help.shapediver.com/doc/shapediver-for-wordpress-and-woocommerce.md)). The action can be triggered in the App using an [Action Control](https://help.shapediver.com/doc/action-control.md) button, or used in other contexts (upcoming feature). ## Inputs of the component Since the *Add to Cart Action* creates a model state, the component exposes the same inputs as the *Create Model State Action* components, plus these additional ones: * Quantity The quantity to be used for the line item. * Price The price to be used for the line item. * Description The description to be used for the line item. Include the placeholder `{modelStateId}` to turn the description in the cart into a link that allows the user to go back to the configurator and continue editing. ## Tutorial models The following sections of our tutorial center contain models including this component: * * --- language: "en" --- # Advanced / Integration * [Three.js Objects](https://help.shapediver.com/doc/three-js-objects.md) * [Augmented Reality (AR)](https://help.shapediver.com/doc/augmented-reality-ar.md) * [glTF Loader](https://help.shapediver.com/doc/gltf-loader.md) * [Framework Integration (React, Next.js)](https://help.shapediver.com/doc/framework-integration-react-next-js.md) --- language: "en" --- # Agent Skills ShapeDiver provides a set of open-source [Agent Skills](https://agentskills.io/home) that give AI coding assistants expert-level knowledge about building ShapeDiver 3D configurators. When installed, these skills allow tools like GitHub Copilot, Claude Code, Cursor, and many others to generate correct, production-ready ShapeDiver integration code without you having to look up API details manually. ## What are Agent Skills? Agent Skills are a standardized way to provide specialized instructions to AI coding assistants. They work through a mechanism called progressive disclosure: your AI assistant knows what skills are available at all times, but only loads the detailed instructions when they become relevant to your task. In practice, this means that once you install the ShapeDiver skills, your AI assistant will automatically recognize when you are working on a ShapeDiver project and provide accurate guidance. ## Available Skills The following skills are included in the [shapediver/agent-skills](https://github.com/shapediver/agent-skills) repository: | Skill | Description | |----------------------------------|---------------------------------------------------------------------------------------------------| | **shapediver-router** | Entry point for all ShapeDiver projects. Identifies integration strategy and gathers credentials. | | **shapediver-viewer** | Viewer V3 API for custom 3D configurators, including interaction features (CDN, NPM, React). | | **shapediver-appbuilder** | App Builder router --- guides to iframe, theme, or fork strategy. | | **shapediver-appbuilder-iframe** | App Builder iframe embedding --- fastest path, zero code. | | **shapediver-appbuilder-theme** | App Builder with optional custom theme (colors, fonts, logo). | | **shapediver-appbuilder-fork** | Fork the open-source App Builder React app for custom components. | | **shapediver-headless** | Headless/server-side integration via the Geometry SDK. | ## How the skills work together When you ask your AI assistant to help with a ShapeDiver project, the **router skill** activates first. It asks a few clarifying questions to understand your needs and collects the credentials required to work with your model. Based on your answers, it hands off to the appropriate implementation skill. For example: * If you say "I want to embed my configurator on my website with no code," the router directs to the **App Builder iframe** skill. * If you say "I need custom drag-and-drop interactions in my 3D viewer," the router directs to the **Viewer** skill. * If you say "I want to trigger exports from my backend," the router directs to the **Headless** skill. This ensures you always get relevant guidance without being overwhelmed by documentation for features you do not need. ## Installation ### Option 1: GitHub CLI (recommended) Bash # Interactive --- choose which skills to install and for which agent gh skill install shapediver/agent-skills Requires the [GitHub CLI](https://cli.github.com/) with `gh skill` support. This launches an interactive prompt where you choose which skills to install and which AI assistant you are using. We recommend to always install **all** skills. ### Option 2: Manual If you prefer not to use the GitHub CLI, you can clone the repository and copy the skill folders into your agent's skills directory: Bash # Clone the repository git clone https://github.com/shapediver/agent-skills.git # Ensure the target directory exists mkdir -p .agents/skills # Copy the skill folders directly into your project cp -r agent-skills/skills/* .agents/skills/ # Clean up the cloned repository folder (optional but recommended) rm -rf agent-skills The exact directory depends on which AI assistant you are using: | Agent | Project scope | User scope | |----------------|----------------------------------------|---------------------------------------------| | GitHub Copilot | `.github/skills/` or `.agents/skills/` | `~/.copilot/skills/` or `~/.agents/skills/` | | Claude Code | `.claude/skills/` or `.agents/skills/` | `~/.claude/skills/` | | Cursor | `.cursor/skills/` or `.agents/skills/` | `~/.cursor/skills/` | | Others | `.agents/skills/` | `~/.agents/skills/` | **Project scope** means the skills are available only within a specific project directory. **User scope** means they are available across all your projects. ## Supported AI assistants The skills follow the open Agent Skills specification and are compatible with any AI coding assistant that supports the standard. This includes GitHub Copilot, Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Roo Code, Amp, Goose, and [many more](https://cli.github.com/manual/gh_skill_install). ## Updating skills To update to the latest version of the skills: Bash gh skill update --all Or, if you installed manually, repeat the clone and copy steps described above. --- language: "en" --- # Animations A feature that can make your models much more lively is animations. In our viewer, animations can be defined by using `AnimationData`. An `AnimationData` consists of one or multiple `AnimationTracks`. The `AnimationTracks` define which object moves how. The `AnimationData` is a wrapper around multiple `AnimationTracks` to execute them together. In this tutorial, we'll show you how to do that, and what is possible. *** ** * ** *** ## Simple Example In our first, simple example, we just want to move our whole model to one side and back. We start with the simple example and now create an `AnimationTrack` array and an `AnimationData` item. The `AnimationData` specifies keyframes (in seconds) at which a state is defined. In our example, we start at second `0` at the position `[0,0,0]`, and move in the next `2.5` seconds to position `[25,0,0]`, from second `2.5` to second `5` we move from that position back to the origin. As a `node` the current session node is defined. As a `path` the type of animation is used, in our case `translation`. And finally, we define the `interpolation` as `linear`. The created data item has to be added to the scene now. Additionally, we want the animation to loop. Therefore, we set the according values. *Note: It does not matter where you add this* `AnimationData`*. The nodes that are specified by the tracks will be animated. It does make sense to store this data in the corresponding session node, as customization calls will remove that node, and therefore invalid nodes in the tracks will not be used.* In the example below we can see the model moving the specified animation sequence in repeat. TypeScript const tracks: IAnimationTrack[] = [ { times: [0, 2.5, 5], values: [0, 0, 0, 25, 0, 0, 0, 0, 0], node: session.node, path: "translation", interpolation: "linear" } ]; const data = new AnimationData("myAnimation", tracks, 0, 5); session.node.data.push(data); data.repeat = true; data.startAnimation(); *** ** * ** *** ## Advanced Example In our next example, we want to move separate parts of the model. We also want to use the other types of animations and want to build them up consecutively. First, we want our door to move, then rotate, and then move back. In our first `AnimationTrack` we create the translation. Note that we stay at the position `[14.5,0,0]` for 5 seconds (from `2.5` to `7.5`). In our second `AnimationTrack` we rotate the object around the z-Axis for 180 degrees. This results in the animation below. *Hint: Clicking* ***Click to Run*** *opens a standalone environment with a live preview and direct links to the* ***CodeSandbox*** *project and* ***GitHub*** *source code.* *** ** * ** *** Additionally, we now also want to scale some of our geometry. We create new `AnimationTracks` and specify different scaling for three of the horizontal boards. In the example below, you can see how both of these animations work at the same time. *Hint: Clicking* ***Click to Run*** *opens a standalone environment with a live preview and direct links to the* ***CodeSandbox*** *project and* ***GitHub*** *source code.* *** ** * ** *** ## Global Access \& GLTF Animations It is very easy to access all animations that are currently active. Just call `viewer.animations` to get all current animations in array form. There you can start/pause/stop them and change if they should be repeated or not. Animations that are defined in a glTF v2 can be accessed exactly in the same way. *** ** * ** *** ## Additional Examples Additional example can be found on the [viewer examples page in the animations section](https://viewer.shapediver.com/v3/examples/index.html#animations). --- language: "en" --- # Anti-Aliasing When using post-processing effects, aliasing effects occur as the effects require that the images are rendered to a texture first to be able to manipulate them. This means that the browser side anti-aliasing, that is used per default, cannot be used anymore. Therefore, manual anti-aliasing techniques have to be used to improve the rendering quality. Anti-aliasing is a technique used in computer graphics to reduce the visual artifacts known as "jaggies" or aliasing, which occur when rendering high-resolution images or 3D scenes at lower display resolutions. Aliasing occurs because of the discrete nature of digital displays, where straight lines and diagonal edges can appear jagged or stair-stepped, leading to a loss of image smoothness and visual quality. The primary goal of anti-aliasing is to smooth out these jagged edges and make the rendered image appear more natural and visually pleasing. It achieves this by introducing additional visual information between the pixels, effectively blending colors to create the illusion of a higher resolution or a smoother image. Via the properties `antiAliasingTechnique` and `antiAliasingTechniqueMobile` we make it possible to choose which anti-aliasing technique (`ANTI_ALIASING_TECHNIQUE`) is used when post-processing effects are activated. In the following section we highlight the 3 different techniques you can choose from. It is also possible to not use anti-aliasing at all, although this option is not recommended for most use cases. ## Techniques ### FXAA `ANTI_ALIASING_TECHNIQUE.FXAA` FXAA is a post-processing technique that operates on the final image and detects edges to smooth them out using various filtering methods. It is computationally inexpensive but may result in some loss of detail. *Fastest, but inaccurate* [Postprocessing Package Reference](https://pmndrs.github.io/postprocessing/public/docs/class/src/effects/FXAAEffect.js~FXAAEffect.html) ### SMAA `ANTI_ALIASING_TECHNIQUE.SMAA` SMAA combines edge detection with a variety of smoothing techniques to provide high-quality anti-aliasing with minimal performance impact. *Fast, but can still lead to artefacts* [Postprocessing Package Reference](https://pmndrs.github.io/postprocessing/public/docs/class/src/effects/SMAAEffect.js~SMAAEffect.html) ### SSAA `ANTI_ALIASING_TECHNIQUE.SSAA` This method involves rendering the scene multiple times with a minimal offset and averaging the colors of neighboring pixels, which effectively reduces aliasing. However, SSAA can be computationally expensive as it requires rendering the scene multiple times. With the property `ssaaSampleLevel` it is possible to adjust the number of samples that are taken. Specified as n, where the number of samples is 2\^n, so ssaaSampleLevel = 4, is 2\^4 samples, 16. *Slower, but high quality* --- language: "en" --- # API Authorization There are two groups of calls to the Geometry Backend API, which use different methods of authorization. Please refer to the [Swagger API documentation](https://help.shapediver.com/doc/getting-started-sdks-examples-documentation.md) for a complete list of API calls. ## Calls based on a `session id` The concept of sessions is used to provide a basic level of protection for your models when embedding them from web browsers (typically using our [viewer](https://help.shapediver.com/doc/viewer.md)). Sessions are also used for the purpose of billing API usage and have a [limited lifetime](https://help.shapediver.com/doc/sessions-and-their-lifetime.md). Note: When viewing the [Swagger documentation](https://help.shapediver.com/doc/getting-started-sdks-examples-documentation.md), watch out for `{sessionId}` to identify calls based on a session id. A typical use case for embedding a ShapeDiver model in a browser is a publicly available product configurator. The [viewer](https://help.shapediver.com/doc/viewer.md) needs to access the metadata of the models (What are the parameters? Which outputs and exports exist for the model?), and it needs to trigger computation requests and download the resulting output data. This implies that the related API calls need to be accessible to anyone accessing your product configurator. On the other hand, your competitors should not be able to embed your models. This is achieved by checking the [origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin) of requests to the Geometry Backend against the [whitelisted domains](https://help.shapediver.com/doc/setup-domains-for-embedding.md) for your model. A new session is created by sending a [session init call](https://sdeuc1.eu-central-1.shapediver.com/api/v2/docs/#/session/post_api_v2_ticket__ticketId_) including a **ticket** for your model to the Geometry Backend. The viewer does this whenever loading a ShapeDiver model, e.g. whenever you open or reload a web page that embeds a model. Read more about [how the viewer represents sessions here](https://help.shapediver.com/doc/sessions.md). The **ticket** is an API key for your model and is required for creating new sessions. Please use the Platform to obtain a ticket depending on the type of your application: * [Ticket for embedding](https://help.shapediver.com/doc/developers-settings.md): Use this type of ticket in case your application runs in a web browser. * [Ticket for backend access](https://help.shapediver.com/doc/developers-settings.md): Use this type of ticket for applications that do not run in a web browser. Note: It is possible to request tickets programmatically by using the [Platform Backend API](https://help.shapediver.com/doc/platform-backend.md#Platform-Backend-API). ### Examples * [Create (initialize) a new session](https://sdeuc1.eu-central-1.shapediver.com/api/v2/docs/#/session/post_api_v2_ticket__ticketId_) * [Compute outputs](https://sdeuc1.eu-central-1.shapediver.com/api/v2/docs/#/output/put_api_v2_session__sessionId__output) * [Compute exports](https://sdeuc1.eu-central-1.shapediver.com/api/v2/docs/#/export/put_api_v2_session__sessionId__export) ### JWT authorization for sessions While session-based authorization is sufficient for many web applications like e-commerce configurators, the Geometry Backend allows configuring your models to require a stronger authorization mechanism for creating and accessing sessions, using a **ticket and a** [**JWT**](https://en.wikipedia.org/wiki/JSON_Web_Token). The corresponding model setting on the [Platform Backend API](https://help.shapediver.com/doc/platform-backend.md#Platform-Backend-API) is called `require_token`. This can be enabled per model or globally for all models of your user or organization account (setting `force_require_token`). Once this is enabled, your models can not be embedded anymore without providing a ticket **and** a JWT to the viewer. Note: The [Platform Backend API](https://help.shapediver.com/doc/platform-backend.md#Platform-Backend-API) offers functionality for programmatically obtaining both JWT and ticket for your model. ## Calls based on a `model id` These calls identify a model based on its unique id. They must be authorized by a [**JWT**](https://en.wikipedia.org/wiki/JSON_Web_Token) which can be obtained using the [Platform Backend API](https://help.shapediver.com/doc/platform-backend.md#Platform-Backend-API). Depending on the [scope](https://www.rfc-editor.org/rfc/rfc8693.html#name-scope-scopes-claim) of the **JWT**, specific permissions are granted or not. These calls are used to manage models. For example, the Platform Backend issues a [create model call](https://sdeuc1.eu-central-1.shapediver.com/api/v2/docs/#/model/post_api_v2_model) to the user's Geometry Backend system when [uploading a new model](#), and it uses an [update model call](https://sdeuc1.eu-central-1.shapediver.com/api/v2/docs/#/model/put_api_v2_model__modelId_) when you save a model on the [Edit screen](#). Note: When viewing the [Swagger documentation](#), watch out for `{modelId}` to identify these calls. Some of the permissions are available to the Platform Backend only, and are never provided as part of the JWTs which you can obtain using the Platform Backend API. As an example, this is the case for the permissions required to update embedding settings for your models, and other settings related to enforcement of product features. You can make use of the [Platform Backend API](https://help.shapediver.com/doc/platform-backend.md#Platform-Backend-API) to programmatically update those settings within the limits of your subscription. ### Examples * [Get information about a model](https://sdeuc1.eu-central-1.shapediver.com/api/v2/docs/#/model/get_api_v2_model__modelId_) * [Download the Grasshopper file of a model](https://sdeuc1.eu-central-1.shapediver.com/api/v2/docs/#/model/get_api_v2_model__modelId__file_download) --- language: "en" --- # API Reference ↗ [Click here to open the API Reference in a new tab.](https://viewer.shapediver.com/v3/latest/api/index.html) --- language: "en" --- # APIs and SDKs You want to develop an application that directly accesses the backend systems of ShapeDiver, bypassing the [Viewer](https://help.shapediver.com/doc/viewer.md)? This section is for you. If you are interested in frontend development using our 3D Viewer, please head over to [Viewer](https://help.shapediver.com/doc/viewer.md). * [Geometry Backend](https://help.shapediver.com/doc/geometry-backend.md) * [Platform Backend](https://help.shapediver.com/doc/platform-backend.md) * [sdTF - Structured data transfer format](https://help.shapediver.com/doc/sdtf-structured-data-transfer-format.md) ## API disambiguation ### Geometry Backend API The [Geometry Backend](https://help.shapediver.com/doc/geometry-backend.md) is where your Grasshopper models are hosted, computations are run, and results of computations are cached. Use the [Geometry Backend API](https://help.shapediver.com/doc/geometry-backend.md#Geometry-Backend-API) to do things like * triggering computations and exports, * listing the parameters (the inputs) and the outputs of your models, * requesting cached computation results, and * querying logs for your model. As an example, our [Viewer](#) is a client application of the Geometry Backend API. Depending on your use case you need a **ticket** (an API key) and/or a **JWT** for accessing your model using the Geometry Backend API. Please jump to section [API Authorization](https://help.shapediver.com/doc/api-authorization.md) to read about this. We operate several Geometry Backend systems, whose computational resources are shared among our users. Enterprise customers are provided with a dedicated Geometry Backend system. We offer [SDKs for .NET and TypeScript](https://help.shapediver.com/doc/getting-started-sdks-examples-documentation.md) to simplify the usage of the Geometry Backend API. ### Platform Backend API The [Platform Backend](https://help.shapediver.com/doc/platform-backend.md) is where users of the ShapeDiver Platform and their models are managed. The Platform Backend is the central authority that manages and provides access to your models running on one of the Geometry Backend systems. Use the Platform Backend API to do things like * listing or updating properties of your models, * creating new models (this also involves the [Geometry Backend API](https://help.shapediver.com/doc/geometry-backend.md#Geometry-Backend-API) for uploading the model), * requesting **tickets** and **JWTs** for your models (allowing to access them using the [Geometry Backend API](https://help.shapediver.com/doc/geometry-backend.md#Geometry-Backend-API)), * querying aggregated analytics for your user. As an example, the [Online platform](https://help.shapediver.com/doc/online-platform.md) is a client application of the Platform Backend API. We also offer [SDKs for .NET and TypeScript](https://help.shapediver.com/doc/platform-backend.md) for the Platform Backend. ### Viewer API Our [Viewer](https://help.shapediver.com/doc/viewer.md) offers an API on its own, which is **not a REST API** but simply a well-defined API used to control the viewer when embedding it into web applications. The Viewer is a client application of the Geometry Backend, it talks to a Geometry Backend system using the Geometry Backend API explained above. --- language: "en" --- # App Builder The "App Builder" section of the plugin includes components for specifying the logic and interface of ShapeDiver Apps. This section will soon detail the functionality of all components of the plugin. Until then, find an overview and examples of the App Builder in the corresponding [section](https://help.shapediver.com/doc/build-apps-in-grasshopper.md). Read more about [ShapeDiver Apps](https://help.shapediver.com/doc/shapediver-app-builder.md). * [Layout Components](https://help.shapediver.com/doc/layout-components.md) * [General Widget components](https://help.shapediver.com/doc/widget-components.md) * [Control Components](https://help.shapediver.com/doc/control-components.md) * [Action Components](https://help.shapediver.com/doc/action-components.md) * [Chart Widget Components](https://help.shapediver.com/doc/chart-widget-components-and-utilities.md) * [Misc](https://help.shapediver.com/doc/misc.md) --- language: "en" --- # App Builder AI Agent We have started developing an AI agent for App Builder and are making it available to early testers. The AI agent should still be considered **beta** , and it may still change considerably. We are excited to receive your feedback via our [forum, community catchups, or onboarding calls](https://help.shapediver.com/doc/community-and-support.md). ## How it works The App Builder AI agent knows your app's parameters and can receive a context string from Grasshopper. You can generate this context string parametrically in Grasshopper, and provide relevant information about your app to the agent. If you use the App Builder [Parameter Control](https://help.shapediver.com/doc/parameter-control.md) component in Grasshopper to define tooltips for your parameters, these are available to the AI agent and provide further context to improve the agent's understanding of your app. You can download an example Grasshopper model from [here](https://shapediverdownloads.s3.us-east-1.amazonaws.com/DemoModels/11-AppBuilder/AppBuilder_AI_Agent_Cube.ghx). The AI agent widget can be placed in your containers like any other widget. The user can enter chat messages, and optionally include a screenshot of the scene or another image as further context. The chat history is shown below. Give it a try: ### Bookshelf example This example uses a context string and parameter tooltips, therefore providing some level of context to the AI agent: [https://appbuilder.shapediver.com/v1/main/latest/?slug=bookshelf-exportable-agent\&openaiApiKey=YOUR_OPENAI_API_KEY](https://appbuilder.shapediver.com/v1/main/latest/?slug=bookshelf-exportable-agent&openaiApiKey=YOUR_OPENAI_API_KEY) ### Your model You can try the agent using any of your models using the following URL pattern. Please provide a context string and parameter tooltips from Grasshopper as shown in the example Grasshopper model available for download above. [https://www.shapediver.com/app/builder/v1/main/latest/?slug=YOUR_SLUG\&openaiApiKey=YOUR_OPENAI_API_KEY](https://www.shapediver.com/app/builder/v1/main/latest/?slug=YOUR_SLUG&openaiApiKey=YOUR_OPENAI_API_KEY) ## Implementation details The source code of the AI agent is part of App Builder Open-Source SDK. You can find the source code of the agent widget [here](https://github.com/shapediver/AppBuilderShared/blob/task/SS-8371--2/components/shapediver/appbuilder/widgets/AppBuilderAgentWidgetComponent.tsx). ## Limitations ### API key visibility Currently, the AI agent communicates directly from the browser with OpenAI's API, which prevents the API key from being protected. You can provide the API key via a property in your [theme file](https://help.shapediver.com/doc/customize-a-theme.md)or as a URL parameter, as described below. We intend to extend the AI agent by a backend application that will act as a proxy and remove the need to expose the API key. We will likely offer the possibility of charging for LLM usage via our credit system. ### Limited parameter types The AI agent currently supports the following parameter types: * Number (float, integer, even integer, odd integer) * Boolean * String (see [Direct Text Input](https://help.shapediver.com/doc/direct-text-input.md)) * String list (value lists) * Color Support for further parameter types like File will be added. ### Distribution The AI agent is now part of App Builder's `main` distribution. ## Configuration You can configure the AI agent using properties in your [theme file](https://help.shapediver.com/doc/customize-a-theme.md)or as URL parameters. The following table shows the available properties and provides examples. | **Property** | **Description** | |----------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `openaiApiKey` | Your [OpenAI API key](https://platform.openai.com/docs/quickstart). | | `model` (defaults to `gpt-4o-mini`) | The [model](https://platform.openai.com/docs/models#current-model-aliases) to use for the [chat completion](https://platform.openai.com/docs/api-reference/chat) API calls. | | `maxHistory` (defaults to 10) | The maximum history of chat messages to use for [chat completion](https://platform.openai.com/docs/api-reference/chat) API calls. | | `debug` | Set this to `true` to show the system prompt and the context string provided from Grasshopper. This is useful for debugging and experimenting. ![image-20250228-094520.png](https://help.shapediver.com/__attachments/a_46a1635f66d142225e659704f6d1ba4963a35d86732b757b594508b600441940/image-20250228-094520.png?cb=5f554df075b41af14f7b5f1f4b0e4a39) | | `systemPrompt` Theme property only | Setting this property overrides the default system prompt. | | `authorContext` Theme property only | This overrides the context string provided from Grasshopper. Useful for debugging and experimenting, or if your Grasshopper model does not output a context string at all. | | `parameterNamesToInclude` Theme property only | Array of names of parameters that should be made available to the AI agent. This can be provided from Grasshopper as well. | | `parameterNamesToExclude` Theme property only | Array of names of parameters that should NOT be made available to the AI agent. This can be provided from Grasshopper as well. | | `langfuseSecretKey` `langfusePublicKey` `langfuseBaseUrl` (optional) | [Langfuse](https://langfuse.com/) is an LLM engineering platform that allows to trace and evaluate LLM applications. Set these properties to enable tracing of the AI agent to Langfuse. | ### Examples A theme file for providing the OpenAI API key, specifying a different LLM, overriding the system prompt, and switching on debug mode: { "version": "1.0", "themeOverrides": { "components": { "AppBuilderAgentWidgetComponent": { "defaultProps": { "openaiApiKey": "YOUR_OPENAI_API_KEY", "model": "chatgpt-4o-latest", "systemPrompt": "You are a helpful assistant that can modify parameters of a 3D configurator and answer questions about the 3D configurator based on the user's input and the context provided. You may answer questions by the user without changing parameters.", "debug": true } } } } } You can achieve a similar result (without overriding the system prompt) using this URL: [https://appbuilder.shapediver.com/v1/main/latest/?slug=YOUR_SLUG\&model=gpt-4o-2024-11-20\&debug=true\&openaiApiKey=YOUR_OPENAI_API_KEY](https://appbuilder.shapediver.com/v1/main/latest/?slug=YOUR_SLUG&model=gpt-4o-2024-11-20&debug=true&openaiApiKey=YOUR_OPENAI_API_KEY) --- language: "en" --- # App Builder Open-Source SDK The entire App Builder code is available in the open-source [AppBuilderSdk repository](https://github.com/shapediver/AppBuilderSdk) built on top of the React framework. You can find all the instructions to get started and fork the repository on [GitHub](https://github.com/shapediver/AppBuilderSdk). We welcome contributions from the community and look forward to welcoming more components, templates and themes in the future! --- language: "en" --- # App Builder Release Notes [You can see the App Builder Release Notes on out Github Release Notes page.](https://github.com/shapediver/AppBuilderSdk/releases) --- language: "en" --- # App iframe embedding ShapeDiver users who have the right permissions are able to embed any of their ShapeDiver Apps using an iframe on any external website they choose. ## Prerequisite: Set up embedding domains In order to embed any model, at least one domain needs to be listed in the "Global domains" for the account. ShapeDiver users with the required permissions can list domains for embedding in the "Settings" page of their dashboard. [Read more about embedding domains.](https://help.shapediver.com/doc/setup-domains-for-embedding.md) ## Allow iframe embedding The second step is to allow embedding for each specific model. This option can be found in the "Edit" page of the model, in the "Iframe" section. Make sure the "Allow iframe embedding" option is checked and Save the changes if needed. Read more about [Iframe settings](https://help.shapediver.com/doc/iframe-settings.md). ## Customize the iframe code It is possible define the desired height and width of the iframe before generating the code. ## Copy the iframe code Once you are happy with the chosen options, use the copy button to copy the iframe code. --- language: "en" --- # Are Grasshopper scripting components supported? All native script components in Grasshopper can be used on ShapeDiver by users with a paid ShapeDiver subscription. However, there are some points to keep in mind when uploading models that include script components. ## Manual checking process Every script included in an uploaded model will go through a manual reviewing process, so as to check that it does not make use of any [functionalities that are forbidden on ShapeDiver](https://help.shapediver.com/doc/forbidden-grasshopper-functionalities.md), nor does it contain malicious code that could damage the ShapeDiver servers. Our team manually reviews all uploaded scripts, which are either approved for ShapeDiver usage or denied. This review process is usually done within a few hours, after which you will receive a platform notification and a confirmation email if your settings have allowed it. Once the review is complete, the upload process can resume from the edit screen of the model. The model will be published after first clicking "Save" from the edit screen. ## Previously approved scripts The manual checking process happens only the first time a script is included in an uploaded Grasshopper definition. As long as the script is not modified, further uploads will skip the checking step and can be automatically approved by the platform. ## Manage assemblies in C# and VB scripts This section applies to the scripting components in Rhino 6 and 7. C# and VB scripts allow referencing local DLLs from the script context menu: ![image-20240308-130922.png](https://help.shapediver.com/__attachments/a_d4cb6bb324d617a71e7fd1c989e57c7ddf43ddaa069c0df4403828c18050098e/image-20240308-130922.png?cb=2a21ad35b236339d727c6ab38e005d09) Since the local file system on ShapeDiver servers cannot be accessed, this is typically not allowed. ## Referencing external packages in C# and Python scripts in Rhino 8 In Rhino 8, the [new scripting editor](https://www.rhino3d.com/features/developer/scripting/) now allows referencing nuget packages in C#, as well as [PyPI](https://pypi.org/) packages in Python. Such external libraries are compatible with ShapeDiver. However, any newly referenced library will go through the usual manual checking process by our team members. A thorough review of the library and its functionalities will be done before allowing its installation and further usage on ShapeDiver servers. Every library that passes the checking process will be preinstalled on our servers. Referencing python libraries or nuget packages works using the `# r` syntax as described in the [ScriptEditor documentation](https://developer.rhino3d.com/guides/scripting/scripting-command/#using-packages). You mustn't specify a precise version number of the library you are using, because this will break your script sooner or later (when we update libraries to newer versions). Instead, either do not specify a version number, or specify a minimum version number. Examples: C# scripts using nuget packages: `#r "nuget: NPOI"` or `#r "nuget: NPOI >= 2.7.3"` Python scripts: `# r: numpy` or `# r: numpy>=2.0.2` **List of currently allowed external packages** For C# scripts: * [NPOI 2.7.3](https://www.nuget.org/packages/NPOI/2.7.3) * [System.IO.Compression 4.3.0](https://www.nuget.org/packages/System.IO.Compression/4.3.0) * [Newtonsoft.Json 13.0.3](https://www.nuget.org/packages/Newtonsoft.Json/13.0.3) * [PdfPig 0.1.14](https://www.nuget.org/packages/PdfPig/0.1.14) * [SixLabors.Fonts 2.1.3](https://www.nuget.org/packages/SixLabors.Fonts/2.1.3) * [StraightSkeletonNetCore 0.0.1](https://www.nuget.org/packages/StraightSkeletonNetCore/0.0.1) * [System.Text.Json 9.0.5](https://www.nuget.org/packages/System.Text.Json/9.0.5) For Python scripts: * [compas 2.11.0](https://pypi.org/project/compas/2.11.0/) * [manifold3d 3.2.0](https://pypi.org/project/manifold3d/3.2.0/) * [matplotlib 3.9.4](https://pypi.org/project/matplotlib/3.9.4/) * [numpy 2.0.2](https://pypi.org/project/numpy/2.0.2/) * [openai 1.65.4](https://pypi.org/project/openai/1.65.4/) * [pandas 2.2.3](https://pypi.org/project/pandas/2.2.3/) * [plotly 6.0.0](https://pypi.org/project/plotly/6.0.0/) * [plyfile 1.1.2](https://pypi.org/project/plyfile/1.1.2/) * [pydantic 2.11.7](https://pypi.org/project/pydantic/2.11.7/) * [PyNiteFEA 1.6.2](https://pypi.org/project/PyNiteFEA/1.6.2/) * [scipy 1.13.1](https://pypi.org/project/scipy/1.13.1/) * [shapely 2.0.7](https://pypi.org/project/shapely/2.0.7/) * [structuralcodes 0.6.3](https://pypi.org/project/structuralcodes/0.6.3/) * [sympy 1.13.3](https://pypi.org/project/sympy/1.13.3/) * [tabulate 0.9.0](https://pypi.org/project/tabulate/0.9.0/) * [topologicpy 0.7.66](https://pypi.org/project/topologicpy/0.7.66/) * [trimesh 4.7.1](https://pypi.org/project/trimesh/4.7.1/) ## Script components on Enterprise systems ShapeDiver Enterprise subscriptions include dedicated [Geometry Backend](https://help.shapediver.com/doc/geometry-backend.md) systems (i.e., dedicated sets of servers) for specific clients. On such dedicated systems, scripting restrictions can be relaxed to a large extent. However, we recommend our clients thoroughly understand the limitations of several functionalities in the context of remote computations. Enterprise clients further have the ability to completely disable the manual checking process in order to get their models instantly approved after uploading. --- language: "en" --- # Area Chart Widget *This section is under construction!* --- language: "en" --- # Attach Transformations ## Introduction When the same geometry element is reused multiple times before it is sent to one of the ShapeDiver [Display](https://help.shapediver.com/doc/display.md) components, it is possible to define only one instance of this object, and attach a special attribute to this object containing an array of transformations. When doing so, transferring data to and from the ShapeDiver servers becomes much more efficient because a single instance of the object is transferred. When it is received by the ShapeDiver viewer, the viewer parses the transform attribute and is in charge of displaying the various instances corresponding to the transfomations stored in the object. Consider the following definition: ![image-20211228-152957.png](https://help.shapediver.com/__attachments/a_262d5c36a5732bb6bd9c4566ec09813da88e50f4818787bde507772f7350e32d/image-20211228-152957.png?cb=636a33098112dc13fe14f7eff749ad26) The same sphere is translated and copied multiple times. All 10 instances of the mesh are sent to the glTF 2.0 Display component, which will store all of them in the solution that will be transferred through the servers. ## Attaching transformations Attached transformations will only be displayed in the Rhino viewport and in the online viewer when used along with the [glTF 2.0 Display](https://help.shapediver.com/doc/gltf-2-0-display.md) component. This definition can be slightly modified: instead of transforming the sphere, use the transfomation (X) output of the *Move* component to attach the list of transformations using the Attach Transformations component: ![image-20211228-153506.png](https://help.shapediver.com/__attachments/a_22983f680f536405a2465415bf776cf13f532c347e1d5b3b0dbf5aa1f3f15efc/image-20211228-153506.png?cb=719fb663caf746f4332ac1df260a852e) In this case, a single mesh is sent to the display component, resulting in an output size around 10 times lighter than in the previous example. In practice the *Attach Transformations* component stores the array of transformations in a specific attribute with the name `transform`. For that reason, the `transform` name is reserved and should not be used for other purposes in case you are working with transformations. ## Preview in the Rhino viewport The ShapeDiver display components are able to preview all instances of the transformed geometry, even though only one instance is created in Grasshopper. Thanks to that preview, it is easy to check the final result that the ShapeDiver viewer will render. ## Using Transform Lists In practice, when using the "Attach Transformations" component, the ShapeDiver plugin converts the list of transformations into a single "Tranform List" object that is ready to be stored as an attribute. When extracting again the attribute from the geometry using the [Extract Attributes](https://help.shapediver.com/doc/extract-attributes.md) and [Deconstruct Attributes](https://help.shapediver.com/doc/deconstruct-attributes.md) components, the resulting extracted attribute will be a "Transform List" as described above: ![image-20220929-100530.png](https://help.shapediver.com/__attachments/a_6f6364475aad7e704faf1a6801b787d26f5c0284bca84d736752f043ad86aeee/image-20220929-100530.png?cb=4bb8846aa71168587e6ea76e01d12289) Because of this technical detail, the ShapeDiver plugin also includes components to convert Transform Lists to and from lists of Transformations in Grasshopper. The first use case is to use the [Explode Transform List](https://help.shapediver.com/doc/explode-transform-list.md) component in order to access a list of transformations extracted from geometry as in the example above. Additionally, using the [Create Transform List](https://help.shapediver.com/doc/create-transform-list.md) component can make it more convenient to add a transform attribute to an existing attributes object, which is not possible only with the Attach Transformations component: ![image-20220929-101026.png](https://help.shapediver.com/__attachments/a_2794b6f10649918efce237e04c5e5d0cc3c37636ac0ec21ac6136c08c195149b/image-20220929-101026.png?cb=b2d99ceee12eb6daed01b5ed9608deb4) --- language: "en" --- # Attribute Visualization With our new Grasshopper Plugin and the invention of [sdTF](https://github.com/shapediver/sdTF) a lot more data can be added to your models. This data can potentially be anything at all, in this case, we'll look at how we can visualize primitive data. This can be expanded by yourself to much more complex data though. Attributes are key-value pairs that can be specified at every step of the [node tree](https://help.shapediver.com/doc/the-scene-tree.md). The number and type of attributes does not have to be consistent over the scene tree. They can be completely freely chosen. The complete API documentation of the attribute visualization module can be found [here](https://viewer.shapediver.com/v3/latest/api/features/attribute-visualization/index.html). This is a feature that can be added via a separate CDN or npm-module on top of our viewer module. To install it call Bash npm install --save @shapediver/viewer.features.attribute-visualization or if you use the viewer via a CDN just can just get the `SDVAttributeVisualization` property from the window object. To enable the attribute visualization mode initially two things must happen first. 1. when a session is created, the `loadSdtf` property has to be set to `true` as the attributes are stored within the sdtf data 2. the viewport type has to be set to `RENDERER_TYPE.ATTRIBUTES` *** ** * ** *** ## Attribute Visualization Mode The first thing to do is to switch on the correct rendering mode and initialize the `AttributeVisualizationEngine`. All cubes are now black, as we did not select attributes to display. TypeScript const attributeVisualizationEngine = new AttributeVisualizationEngine( viewport ); *** ** * ** *** In the next demo, we focus on layers. Objects can have layers assigned and these layers can be used to change the opacity and the color of the objects assigned to them. Please note, that the color adjustment is only done as long as there are no attributes selected. TypeScript const attributeVisualizationEngine = new AttributeVisualizationEngine( viewport ); attributeVisualizationEngine.layers["pinky"].opacity = 0.5; attributeVisualizationEngine.layers["brain"].color = "#ff0000"; attributeVisualizationEngine.updateLayers( attributeVisualizationEngine.layers ); *** ** * ** *** In our next step, we now visualize an attribute. We provide the key and type and select a visualization method. Via the call of `api.createSDTFOverview()` you get an overview of all the attribute in the current scene. TypeScript const attributeVisualizationEngine = new AttributeVisualizationEngine( viewport ); attributeVisualizationEngine.updateAttributes([ { key: "x+y, string", type: SDTF_TYPEHINT.STRING, visualization: ATTRIBUTE_VISUALIZATION.GREEN_WHITE_RED } ]); *** ** * ** *** ## Additional Examples Additional example can be found on the [viewer examples page in the attribute visualization section](https://viewer.shapediver.com/v3/examples/index.html#attribute%20visualization). --- language: "en" --- # Attribute visualization mode [Using the ShapeDiver plugin](https://help.shapediver.com/doc/attributes.md), it is possible to store attributes in various elements that are being displayed in the ShapeDiver viewer. Attributes can have multiple applications, one of which being the visualization of various properties associated with each element. After a model is uploaded to ShapeDiver, you can access the attributes visualization mode through the control panel on the right of the model view page: ![image-20220801-085936.png](https://help.shapediver.com/__attachments/a_39427d448c539482ff704fe54dac4a355dc3e2dd7138555eb900a065ec26854b/image-20220801-085936.png?cb=46439cb6c098b9f94eb5ce321fc36f5b) At the top of the section, use the "Enable attribute visualization" toggle to enable the visualization mode. Once the mode is turned on, two things happen: * The materials used in the standard (rendered) mode are switched off for a neutral color, preparing the geometry to be displayed according to the attributes they contain. * Each element of the 3d scene containing attributes is now selectable. Once this mode is enabled, there are two ways to start visualizing attributes. ## Visualize attributes manually Open the "Visualization settings" menu in order to find a list of all attribute keys found in the model. When you select one, all objects containing this attribute will be visualized in the 3d scene according color schemes. Currently, there are several types of attributes that are compatible with visualization: * Numerical attributes (integer and floating numbers) are visualized using a color gradient that is automatically adjusted to the minimal and maximal value of the corresponding attribute in the model. Some adjustments can be made to the visualization: * Adjust the min and max values in order to adapt the gradient and ignore values outside of the specified range. * Choose between a range of color and opacity gradients for the visualization. * Color attributes are visualized with a simple material showing the color corresponding to the visualized attribute. * Text attributes are also visualized with a gradient scheme, each color corresponding to a string value in the list, the strings being ordered alphabetically. Click on the cross next to the attribute in the list to stop visualizing it in the viewer. Other types of attributes will be made visualizable in the future. ### Visualize several attributes It is possible to visualize several attributes at the same time in the viewer. The interface allows selecting multiple attributes and add them to the active list. Whenever an element contains more than one of the active attributes, the used visualization is defined according to the order of attributes in the active list. The topmost attribute in the list always has priority over the lower ones. ## Explore attributes contained in a specific element Once an element is selected, the attributes it contains will be displayed in the control panel on the right. On the one hand, the value of each attribute in the list can be copied using the "copy" button on the right. On the other hand, using the "eye" button will focus the visualization on the selected attribute, displaying the color gradient corresponding to the selected attribute. If an attribute is already being visualized, the selected attribute will be moved to the top of the priority list of visualized attributes. The previously visualized attributes will not be removed from the list. It is always possible to open the "Visualization properties" dropdown afterwards and adjust the gradient scheme as well as the extreme values to span with the gradient. ## Layer attribute Organizing geometry in different layers is a standard way to work in CAD software. For this reason, if the `layer` attribute is found in the model, a layer option will become available while in attributes visualization mode, in the lower left corner of the viewer: ![image-20230314-144908.png](https://help.shapediver.com/__attachments/a_cac42db3fb98054e333fbbb49b6734f58eeee2423546ca4df515403808536980/image-20230314-144908.png?cb=76a53d89af1f7593db8164f4e6bf9371) Each layer can be switched on and off or made partially transparent using the opacity slider. --- language: "en" --- # Attributes ![-JkoPjHT3ggquOayZcfY-WAfygaH8usTdFJYoyjagHSRvo1OnMda_gz1jf_R3zZdLBtSyt2CXUkNNGav2tTlCuB0JDpKwwrpJVozYVSI5P_hN_Biwaoe_5JbzkdZgQCW25mG6iMT](https://help.shapediver.com/__attachments/a_f93d56c4b36785c6e51872e0008a29115a9992a2831969f03f74787c854815dd/-JkoPjHT3ggquOayZcfY-WAfygaH8usTdFJYoyjagHSRvo1OnMda_gz1jf_R3zZdLBtSyt2CXUkNNGav2tTlCuB0JDpKwwrpJVozYVSI5P_hN_Biwaoe_5JbzkdZgQCW25mG6iMT?cb=287bf474bdd540a583fc1a90eb8fd698) This article describes in detail the attributes system and its mechanisms. Check out the [Attributes Cheat Sheet](https://help.shapediver.com/doc/attributes-cheat-sheet.md) for a quick overview of the various use cases for ShapeDiver attributes. ## Introduction One of the main functions of the ShapeDiver plugin is to turn Grasshopper definitions into online interfaces where users can remotely send data (parameters, geometry, images, text files, etc...) and receive data (3d visualization in the online viewer, direct data outputs, exported CAD files, etc...). For the time this data flows through the Grasshopper definition, it is represented through one of the many data types that Grasshopper can handle: multiple geometry and primitive types as listed in the Params category of Grasshopper. However, the data coming to Grasshopper often contains more information than what the standard Grasshopper types contain. For example, when using the [Import Geometry](https://help.shapediver.com/doc/import-geometry.md) component to import a set of curves from a DXF file, the component will send back a list of objects of the Curve type in Grasshopper. But the DXF file does not only contain curves: each might have a name, a layer, and a color, for example. Conversely, when exporting a set of curves using the [Download Export](https://help.shapediver.com/doc/download-export.md) component, one might want to assign the same properties for each object in the resulting file. The above examples are concrete, but in practice, there are various applications where injecting some additional information to the inputs and outputs of an application is very useful. Each object could contain its own material description for the viewer or even custom information that the ShapeDiver viewer can visualize for analysis purposes. ## The Attributes system In order to allow such applications, the ShapeDiver plugin comes with its own Attributes system. In practice, it means that if you have the ShapeDiver plugin installed in Grasshopper, every geometry and primitive supported by the plugin can be *augmented* by injecting an Attributes Object. See below a first simple example of creating an attribute object containing a single key/value pair and injecting this attribute in a mesh. In the end, we verify that the attribute is successfully stored in the mesh by extracting it back and reading its contents: ![image-20211229-095315.png](https://help.shapediver.com/__attachments/a_56a1d064285ac31451cdcc3dc97e5c92f3a5245e34ac7438ae3562ca54b39e65/image-20211229-095315.png?cb=0bccb2d99373ac64136e7ab5bed42060) It is also possible to visualize stored attributes in objects of the canvas by hovering over them or connecting them to a text panel: ![image-20230314-101910.png](https://help.shapediver.com/__attachments/a_b60f0842cd31f6478a0a636557bc09aec6460201cbcf2710dd74fc33b240898b/image-20230314-101910.png?cb=2d54f00baa5044efacf129102a36b085) There are two types of attributes: **reserved attributes** and **custom attributes**. Read more about each of these types below. ## Reserved attributes Reserved attributes are attributes which have a predefined meaning when creating a ShapeDiver application. As an example, the `name` attribute has a specific meaning when importing and exporting files from ShapeDiver: it will map to the native name property of each file type that supports it. For example, 3dm and dxf files support naming objects. The objects imported from these file types come in Grasshopper with a predefined name attribute corresponding to their name in the original document. Conversely, defining a name attribute in geometry before it is exported will automatically set the native name property for the object in the exported document. See below an example application where a 3dm file is imported and the names of objects are changed to add the SD_ prefix before the file is exported again: ![image-20211229-111913.png](https://help.shapediver.com/__attachments/a_658d9b3b4d0bd8f01895f9434618e6b73589be988c2c781dcdc4c29ef1fa30e2/image-20211229-111913.png?cb=d4fcff942054abe7ccf7393a7f76b4fa) Reserved attributes do not map to meaningful properties in all environments. Not all file types support naming or materials for example, therefore name and material attributes are ignored in those cases. Additionally, some attributes, such as the transform attribute, only make sense in the context of the ShapeDiver Display components used by the online viewer to display geometry. Find in the [cheat sheet](https://help.shapediver.com/doc/attributes-cheat-sheet.md) how the list of reserved attributes currently supported (the list will keep growing in the future) behave when used with the various I/O components of the plugin. ### Helper components for reserved attributes Since reserved attributes are likely used more frequently, the ShapeDiver plugin comes with some helper components which automatically build them without having to used the *Construct Attributes* component. Consider the example below where the Export Attributes component provides a condensed way to inject all typical properties one might want to set before exporting files: ![image-20211229-100148.png](https://help.shapediver.com/__attachments/a_41246a8921c04ff57f298c88f220ebfacb30812157b935de771c9eaffe1fc8aa/image-20211229-100148.png?cb=aef418f96f5165f2989ad5422290469e) ## Custom attributes Using the [Construct Attributes](https://help.shapediver.com/doc/construct-attributes.md) and [Inject Attributes](https://help.shapediver.com/doc/inject-attributes.md)components, any set of key/value pairs can be injected in Grasshopper objects. This allows for much flexibility regardless of which client the data is consumed (online viewer, Rhino, in the future many more...). Below are two examples of how custom attributes are leveraged in the viewer and when working with 3dm files. ### Custom attributes and the attribute visualization mode In order to visualize custom attributes in the viewer, one needs to use the [ShapeDiver Output](https://help.shapediver.com/doc/shapediver-output.md) component, which allows to output enriched data, as opposed to the [ShapeDiver Display](https://help.shapediver.com/doc/display.md) components which only support plain geometry and do not retain stored attributes. There are two ways custom attributes can be manipulated in the viewer. First of all, every custom attribute (like reserved attributes) can be accessed through the [viewer API](https://help.shapediver.com/doc/viewer.md) and use for any purpose by a web application. Additionally, the model view page on the ShapeDiver platform includes an attribute visualization panel which lets users switch from the rendered mode. In the attribute visualization mode, it is possible to select any number of attributes for visualization and define gradient color schemes to create analysis models. Read more about the [attribute visualization mode on the platform](https://help.shapediver.com/doc/attribute-visualization-mode.md). ### Custom attributes and 3dm files When importing and exporting 3dm files, there is an explicit mapping between ShapeDiver attributes and [Rhino Attribute User Text](https://docs.mcneel.com/rhino/7/help/en-us/properties/attributeusertext.htm) entities. ## Attributes and desktop clients It is possible to connect the ShapeDiver platform with a range of desktop clients, in order to exchange data and geometry between local software and a ShapeDiver model. In a way similar to the usage of attributes when importing and exporting files from a model, the Attributes system to include metadata about the exchanged objects such as document and object properties. Read more in the [Desktop clients](https://help.shapediver.com/doc/shapediver-desktop-clients.md) section about this use case and how attributes can be used in each of the desktop clients supported by ShapeDiver. ## Supported Attribute types You might have noticed in the table of reserved attributes that not only Text values are supported as attributes, but also various other data types (in the table, Text, Number, Color, ShapeDiver Material, Transforms object). As a matter of fact, most of the data types in Grasshopper are supported as attributes, and can be injected in any object type as well. As an example, it is possible to inject a mesh attribute in a Text. Of course, not all use cases are justified, but the feature has been conceived as flexible for future uses, in accordance with the [sdTF file format](https://github.com/shapediver/sdTF/blob/development/specification/1.0/README.md) we use for transferring data to and from our servers. ## Plugin components Read more about each component of the plugin that supports reading, writing and manipulating attributes. * [Attributes cheat sheet](https://help.shapediver.com/doc/attributes-cheat-sheet.md) * [Construct Attributes](https://help.shapediver.com/doc/construct-attributes.md) * [Inject Attributes](https://help.shapediver.com/doc/inject-attributes.md) * [Extract Attributes](https://help.shapediver.com/doc/extract-attributes.md) * [Deconstruct Attributes](https://help.shapediver.com/doc/deconstruct-attributes.md) * [Access Key](https://help.shapediver.com/doc/access-key.md) * [Add Key-Value Pair](https://help.shapediver.com/doc/add-key-value-pair.md) * [Attach Transformations](https://help.shapediver.com/doc/attach-transformations.md) * [Create Transform List](https://help.shapediver.com/doc/create-transform-list.md) * [Explode Transform List](https://help.shapediver.com/doc/explode-transform-list.md) * [Delete Attributes](https://help.shapediver.com/doc/delete-attributes.md) --- language: "en" --- # Attributes cheat sheet We list in the table below all use cases for the ShapeDiver attribute system. For each case, we link to the relevant parts of the help center, which contain a detailed description as well as example Grasshopper definitions when it is relevant. |------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Attribute name** | **Components of the ShapeDiver plugin** |||| | | [Import Geometry](https://help.shapediver.com/doc/import-geometry.md) *Let users import their own CAD files as inputs to online models.* | [Download Export](https://help.shapediver.com/doc/download-export.md) and [Email Export](https://help.shapediver.com/doc/email-export.md) *Let users export CAD files as outputs to online models.* | [glTF 2.0 Display](https://help.shapediver.com/doc/gltf-2-0-display.md) *Simple display of solutions in the 3D viewer (geometry only, no data structure)* | [ShapeDiver Output](https://help.shapediver.com/doc/shapediver-output.md) *Display solutions in the 3D viewer, including custom attributes that can be visualized and lossless data structure, geometry can be baked in desktop clients.* | | layer | If any of those attributes correspond to a standard property of the imported file format, then the imported geometry will include the respective properties as ShapeDiver attributes. [Read more](https://help.shapediver.com/doc/import-geometry.md#importgeo1) about this use case. | If any of those attributes correspond to a standard property of the imported file format, then the exported geometry will map the stored ShapeDiver attributes to the respective properties of the exported document. [Read more](https://help.shapediver.com/doc/download-export.md#exportgeo1) about this use case. | -- | Used in attribute visualization mode to define layers that can be switched on and off, and adjusted with an opacity control. [Read more](https://help.shapediver.com/doc/shapediver-output.md#layer) about this use case. | | plotcolor | If any of those attributes correspond to a standard property of the imported file format, then the imported geometry will include the respective properties as ShapeDiver attributes. [Read more](https://help.shapediver.com/doc/import-geometry.md#importgeo1) about this use case. | If any of those attributes correspond to a standard property of the imported file format, then the exported geometry will map the stored ShapeDiver attributes to the respective properties of the exported document. [Read more](https://help.shapediver.com/doc/download-export.md#exportgeo1) about this use case. | -- | Can be visualized in attribute visualization mode. Use case identical to custom attributes (see below). [Read more](https://help.shapediver.com/doc/shapediver-output.md#visualization) about this use case. | | plotweight | If any of those attributes correspond to a standard property of the imported file format, then the imported geometry will include the respective properties as ShapeDiver attributes. [Read more](https://help.shapediver.com/doc/import-geometry.md#importgeo1) about this use case. | If any of those attributes correspond to a standard property of the imported file format, then the exported geometry will map the stored ShapeDiver attributes to the respective properties of the exported document. [Read more](https://help.shapediver.com/doc/download-export.md#exportgeo1) about this use case. | -- | Can be visualized in attribute visualization mode. Use case identical to custom attributes (see below). [Read more](https://help.shapediver.com/doc/shapediver-output.md#visualization) about this use case. | | name | If any of those attributes correspond to a standard property of the imported file format, then the imported geometry will include the respective properties as ShapeDiver attributes. [Read more](https://help.shapediver.com/doc/import-geometry.md#importgeo1) about this use case. | If any of those attributes correspond to a standard property of the imported file format, then the exported geometry will map the stored ShapeDiver attributes to the respective properties of the exported document. [Read more](https://help.shapediver.com/doc/download-export.md#exportgeo1) about this use case. | Used to control the data tree of the generated glTF assets used for visualization. [Read more](https://help.shapediver.com/doc/gltf-2-0-display.md#name) about this use case. | Can be visualized in attribute visualization mode. Use case identical to custom attributes (see below). [Read more](https://help.shapediver.com/doc/shapediver-output.md#visualization) about this use case. | | color | If any of those attributes correspond to a standard property of the imported file format, then the imported geometry will include the respective properties as ShapeDiver attributes. [Read more](https://help.shapediver.com/doc/import-geometry.md#importgeo1) about this use case. | If any of those attributes correspond to a standard property of the imported file format, then the exported geometry will map the stored ShapeDiver attributes to the respective properties of the exported document. [Read more](https://help.shapediver.com/doc/download-export.md#exportgeo1) about this use case. | If no `material` is stored in objects, the `color` attribute is used to define a simple material with the defined color. | If no `material` is stored in objects, the `color` attribute is used to define a simple material with the defined color. Can also be visualized while in attribute visualization mode. | | material | If any of those attributes correspond to a standard property of the imported file format, then the imported geometry will include the respective properties as ShapeDiver attributes. [Read more](https://help.shapediver.com/doc/import-geometry.md#importgeo1) about this use case. | If any of those attributes correspond to a standard property of the imported file format, then the exported geometry will map the stored ShapeDiver attributes to the respective properties of the exported document. [Read more](https://help.shapediver.com/doc/download-export.md#exportgeo1) about this use case. | Used for rendering geometry in the viewer. Not exposed in the attributes visualization mode. [Read more](https://help.shapediver.com/doc/gltf-2-0-display.md#attrmat) about this use case. || | transform | -- | -- | Used for sending a unique object with a list of transformations that are used for rendering the object in the online scene.. [Read more](https://help.shapediver.com/doc/attach-transformations.md) about attaching transformations. | -- | | *Any other key*(custom attributes) | For 3dm files with objects containing User Text, and any file format whose properties are mapped to User Text when they are imported to Rhino, the Import Geometry component will map User Text key-value pairs to ShapeDiver Attributes. [Read more](https://help.shapediver.com/doc/import-geometry.md#importgeo2) about this use case. | For 3dm files, and any file format for which User Text in Rhino is mapped to native properties, the Export components will use custom ShapeDiver Attributes to create User Text. [Read more](https://help.shapediver.com/doc/download-export.md#exportgeo2) about this use case. | -- | Custom attributes can be visualized using the attribute visualization mode of the viewer. [Read more](https://help.shapediver.com/doc/shapediver-output.md#visualization) about this use case. | --- language: "en" --- # Audience analytics This section simply contains a link to the global [Account analytics](https://help.shapediver.com/doc/account-analytics.md) section, which provides detailed metrics about the usage of the models of your account. The link from this section loads the account analytics page pre-filtered to show the metrics for the specific model. --- language: "en" --- # Augmented Reality All ShapeDiver models can be viewed in Augmented Reality (AR) when using a compatible device (smartphone or tablet). To set this up correctly, [follow these instructions](https://help.shapediver.com/doc/scene-settings.md). ## From mobile devices To view your models in AR, access the URL of your model from your compatible device (directly on our platform or iframe embedded models) and look for the AR button on the viewer canvas, then tap on it: ![image-20220112-200226.png](https://help.shapediver.com/__attachments/a_eba221f92c878cc4b94a640291aee4df725ea081655de2e03016565463acdaa1/image-20220112-200226.png?cb=96f1ae81d1ea08c2960a9b27206f2237) AR button appears on mobile devices. Close the AR viewer if you wish to return to editing the model. ## From a desktop If you are accessing the model through a desktop, the AR button remains available. When clicking on it, our viewer will also return the whole scene as an AR-ready asset. A QR code is generated that can be scanned by any compatible mobile device. The QR code is valid for a period of**4 weeks** after its time of creation. ![image-20221212-104501.png](https://help.shapediver.com/__attachments/a_dbe7ee47325340b8df19abb5391dd6ed1e63683cef928fd6c350f2343eb4b57b/image-20221212-104501.png?cb=b1ac7be2248936153d206b556c8d22ce) --- language: "en" --- # Augmented Reality (AR) Getting AR into your Viewer only requires two additional calls. One checks it the device supports AR, the other one opens the scene in AR. You can check if the user is currently on one of these devices and start AR like shown in the example below. You can also just go to our [platform](https://shapediver.com/app)and try AR there. TypeScript const token = viewport.addFlag(FLAG_TYPE.BUSY_MODE); if (viewport.viewableInAR()) { await viewport.viewInAR(); } else { const qr = await viewport.createArSessionLink(undefined, true); const image = new Image(); image.src = qr; image.style.position = "absolute"; image.style.bottom = "0%"; document.body.appendChild(image); } viewport.removeFlag(token); *** ** * ** *** ## Scene Setup for AR To ensure that the rendering of your scene in AR is close to the rendering of our viewer, please consider the following points. 1. Use an HDR environment map, preferably one that looks close to the default area where you want to display AR models. 2. Set the texture and output encoding to `srgb` and enable the physically correct light setting. 3. Use as little lights as possible. The lights are not used in AR, therefore, they will change the rendering result noticeably. If you still are not happy with the results, feel free to reach out to us, we are always happy to improve our features! *** ** * ** *** ## Additional Examples Additional example can be found on the [viewer examples page in the augmented reality section](https://viewer.shapediver.com/v3/examples/index.html#augmented%20reality). --- language: "en" --- # Backend settings Take me to my [backend settings](https://www.shapediver.com/app/settings/backend). This page includes information about which backend system is linked to your ShapeDiver account, including the specific Rhino version that is installed there, as well as the list of third-party Grasshopper plugins that can be used. If your account allows it, you can also switch the backend system used for model uploads here. ## Active backend system This section contains general information about the currently active backend system, which is the system that will be used for all future model uploads from your account. The following information is available: |---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | System name | The name used to reference the backend system. | | Description | A short description of the system. | | Model view url | The model view url associated with the system, useful for developers working with the [viewer API](https://help.shapediver.com/doc/viewer) among other applications. | | Rhino version | The Rhino version installed on the backend system. In particular, the first digit represents the major Rhino version (typically Rhino 6 or Rhino 7). You can check the Rhino version you are using locally with the `_AboutRhino` command in Rhino. | | Grasshopper version | The version of Grasshopper installed along Rhino on the backend system. You can check the Grasshopper version you are using locally using the top-level menu: Help \> About. | | ShapeDiver version | The version of the ShapeDiver plugin installed on the backend system. Always make sure to install the latest version from the package manager in Rhino. | **Rhino version** ShapeDiver runs various server systems that support all versions of Rhino from Rhino 6 onwards. Depending on your ShapeDiver subscription, not all versions of Rhino are available for uploads: * *PRO Users are limited to a Rhino 6 backend*. This legacy type of ShapeDiver subscription is not available anymore. * *Free users have access to Rhino 7 and Rhino 8 backends.* * All other paying users based on one of our [current subscriptions](https://shapediver.com/pricing) have access to *all backend systems (Rhino 6, 7 and 8)*. **Update the backend system** Users with access to several backend systems can use the dropdown menu under the table to select a different one. The change is then validated after clicking on the "Save" button from the top right corner of the section. Note that changing the active backend system only affects future uploads! Already uploaded files are not transferred to a new backend system. You can always check on the model view page which system each of your models was uploaded to. ## Active plugins on the system The table in this section provides an always up-to-date list of third-party Grasshopper plugins which can be used in Grasshopper definitions uploaded to the system. For each of the plugins, the following information is available: |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Plugin name | The official name of the plugin. When available, a link next to the name is available to the food4rhino page or official plugin page, where more information and download links are available. | | Installed version | The version of the plugin installed on the system. | | Allowed version | The version(s) of the plugin allowed on the system. This can be a single version or a range of versions, depending on the backwards compatibility of the different versions of this plugin. Any model uploaded with components from a version of this plugin included in this range will be accepted by the backend system. | | Author | The author(s) of the plugin. | | Description | When available, a short description of the plugin functionalities. | | Disallowed components | Some plugins in the list are only partially supported, which means some of their components will be denied when uploading to ShapeDiver. These components are denied because they make use of [functionality that we must forbid](https://help.shapediver.com/doc/forbidden-grasshopper-functionalities.md) for reasons of security and stability. Click on the "Check list" button in this column to get a list of components, including their names and id, which are forbidden to be used and will cause your model to be denied when uploading it. Please remove these components from your definition before uploading, and replace them by alternative components. | --- language: "en" --- # Bar Chart Widget *This section is under construction!* --- language: "en" --- # Billing of API usage Please refer to our [Pricing - Credits](https://help.shapediver.com/doc/credits.md) page for an explanation of **credits**. An excerpt: *When you or others work with your ShapeDiver account, credits are consumed for actions like computing the solution of a Grasshopper model for a set of parameters, generating a file export, or downloading an AR scene.* Billing of the Geometry Backend API usage is based on [sessions](https://help.shapediver.com/doc/sessions-and-their-lifetime.md). There are two types of sessions that we bill for differently: * **Embedded sessions** (sessions created using a [ticket for embedding](https://help.shapediver.com/doc/developers-settings.md)) * Use case: Applications that access the Geometry Backend API from web browsers, like the [Viewer](https://help.shapediver.com/doc/viewer.md) or when using [App Builder](https://help.shapediver.com/doc/shapediver-app-builder.md). This typically means that API actions are somehow triggered by a human being. * Please refer to the explanation of [credit usage of embedded sessions](https://help.shapediver.com/doc/sessions.md#Credit-usage-of-embedded-sessions). * **Backend sessions** (sessions created using a [ticket for backend access](https://help.shapediver.com/doc/developers-settings.md)) * Use case: Applications that access the Geometry Backend API from a backend application (not from a web browser), like E-Commerce or ERP systems. This might include batch processing. --- language: "en" --- # Bloom A bloom post-processing effect is a visual enhancement technique commonly used in computer graphics and video games to simulate the appearance of bright objects. The bloom effect works by extracting the high-intensity portions of the image and spreading their luminance values to the surrounding pixels. This process mimics the way our eyes perceive bright light sources, which often causes a "bleeding" effect or a halo of light. By replicating this phenomenon, the bloom effect adds a sense of realism and cinematic quality to the rendered scene. [Postprocessing Package Reference](https://pmndrs.github.io/postprocessing/public/docs/class/src/effects/BloomEffect.js~BloomEffect.html) *** ** * ** *** ## Properties | **Name** | **Descriptions** | |----------------------|-------------------------------------------------------------------------------------------------------------------------------------| | `BlendFunction` | How the original image and the effect are blended together, in most cases it does not make sense to deviate from the default value. | | `mipmapBlur` | If mipmaps are used for the blurring in the bloom effect. | | `intensity` | The bloom intensity. | | `luminanceSmoothing` | Controls the smoothness of the luminance threshold. | | `luminanceThreshold` | The luminance threshold. Raise this value to mask out darker elements in the scene. | | `kernelSize` | The size of the blur kernel, only works when `mipmapBlur` is disabled. | --- language: "en" --- # Bookmark a model You can bookmark any model on ShapeDiver that you are able to view, as part of the public gallery (public models) or from within your own library. It is possible to bookmark models in the gallery and library pages from the context menu of model cards: ![image-20230707-095711.png](https://help.shapediver.com/__attachments/a_515a497e1bf131e0b5248186cf571b80fe00606040b6411df1e331eee976f04f/image-20230707-095711.png?cb=8cb2aaf2098b2cb844e44124827c136e) In the library, you can also bookmark models in the table view, as part of the model actions on the right: ![image-20230707-095744.png](https://help.shapediver.com/__attachments/a_3339d962c7d54036b69530674910f93cb1b67b78ebd909a78788da32c4f385be/image-20230707-095744.png?cb=c7a945caf38f64f8b887f44255326b50) Models can also be bookmarked as you are interacting with them on the model view page. The bookmark button is located above the viewer canvas: ![image-20230707-095831.png](https://help.shapediver.com/__attachments/a_d0453f8580ec7649d1fdc8e5ee36d294cf93a9574ebfa7c59ff5f201313a1b75/image-20230707-095831.png?cb=e52d34d162f72ecc8e9cb19360faf92b) Once a model is bookmarked, you can always find it from the "Bookmarked" section of your library: ![image-20230707-095621.png](https://help.shapediver.com/__attachments/a_eb4e8b61d834833bf3010cd279850a6ef3024d28e9019df8ee1fa22caff4b406/image-20230707-095621.png?cb=6903d3172657cf26ff9a9cb81fe5af76) --- language: "en" --- # App The *App* component defines a specific type of output that contains the description of a web application's skeleton. Read more [here](https://help.shapediver.com/doc/build-apps-in-grasshopper.md)about the App Builder and how to use it to drive web applications from Grasshopper. ## Inputs The component contains three inputs. * Containers (C): This input is required and accepts a list of containers as defined by [Container](https://help.shapediver.com/doc/build-container.md) components. As an example, the following definition defines an App with two containers named `left` and `right`: ![image-20250923-125450.png](https://help.shapediver.com/__attachments/a_669d040096630aaa03f123b0d2bb49de65d325d96f2c8441ab0e6ba09e50cef9/image-20250923-125450.png?cb=567dc04f9990f5c3de4c6b7f0ae6565e) Depending on the template used, the ShapeDiver App might produce various layouts from this configuration. In the default template, the desktop layout will look like this: ![image-20240502-083808.png](https://help.shapediver.com/__attachments/a_827f79fa24be76fd4063e18bcf246e90e2e1c901318acad3d376033dd75b0129/image-20240502-083808.png?cb=b87fca2c0f2b3da1f0573c8d35cd47df) * Parameters (P): This input is optional and can be used to define so-called *dynamic parameters*. Those parameters are App Builder-specific and contextual to the current state of the online App. This feature is currently experimental and will be documented further as its implementation progresses. * Instances (I): This input is optional and can be used to define separate ShapeDiver model instances to be controlled from the current App. This feature is currently experimental and will be documented further as its implementation progresses. ## Outputs The component does not include explicit outputs in Grasshopper. Once the definition is uploaded to ShapeDiver, its contents will be included in the model's outputs and used to define the user interface of a ShapeDiver App. The corresponding App can be opened from the model view page of the model, using the ["Open App" button](https://help.shapediver.com/doc/explore-apps-from-the-platform.md) above the viewer. --- language: "en" --- # Build Apps in Grasshopper ## Overview With the [App Builder components](https://help.shapediver.com/doc/app-builder.md), one can control the *skeleton* of a web application directly from Grasshopper. After the Grasshopper definition is uploaded, it can be opened as a ShapeDiver App, which reflects the logic and organization defined by those components. ShapeDiver currently provides one *template* that interprets the application's skeleton into a fully responsive layout. In the future, other templates will be available. ## What is the skeleton of a web application? We call the *skeleton* of a web application the abstract description of its hierarchy and logic without considering things such as sizes and positions, colors, fonts, etc... The skeleton can be represented by a tree where nodes consist of a set of different bricks helping to build and organize the web application. At the moment, the App Builder is able to define * The *App* is the top-level node from which all other nodes depend. It has a *name* and a list of *containers*. * *Containers* are the first hierarchy level inside the app. They have a name and can include a list of *tabs* and/or *widgets*. Tabs are optional: a container can only include a list of widgets and skip the tabs level of the hierarchy. * *Tabs* are a way to divide containers into several parts. In the final application, they could be represented by tabs in the container, different boxes, steps in a configurator, etc. Tabs are defined by a name and a list of widgets. * *Widgets* are UI elements specialized for a specific purpose. In the first version of the App Builder tools we introduce below, we have included parameter widgets, image widgets, and text widgets. Chart and legend widgets are planned, and potentially many more in the future. A widget has various custom properties and can include or not lists of *elements*. For example, a parameter widget includes a list of parameter elements. An image widget does not include any further elements but contains custom properties used to define the image. * *Elements* are the lowest elements in the hierarchy. Element is a generic term that can cover many unit layout items. In the first version of our application building tools, only two elements are included (parameter elements and export elements). Here is an example: ![image-20240423-144600.png](https://help.shapediver.com/__attachments/a_b403464d11fd8c8f27806571e5ca947f56e9cea0c8ced718d4d3b128bda879e2/image-20240423-144600.png?cb=26c4544082bafc2561df5bcaab4f5fd2) ## Define a skeleton using the App Builder components The ShapeDiver plugin includes an "App Builder" category, which closely mirrors the various skeleton elements described above. In other words, the components can be used to define the skeleton tree explicitly. **First example** Consider the following Grasshopper definition: ![image-20240423-160559.png](https://help.shapediver.com/__attachments/a_f863041b0d301136d55bda4d1f6ef4c033c2173a7a956de7a013e203945ae1d2/image-20240423-160559.png?cb=172e5c8dfd1574aa03c8aadcf29b628c) Four parameters ("Width, "Height", "Wood Type" and "Color") are used as inputs for an algorithm which produces two outputs: geometry to display in the viewer (using a Display component) and a bitmap asset which is sent to a ShapeDiver Export component called "Drawings". This definition can be uploaded to ShapeDiver as is and opened as a ShapeDiver App, with the standard interface. But it can also be extended with the App Builder components to create an application according to the skeleton above: ![image-20240424-130029.png](https://help.shapediver.com/__attachments/a_6e56caefe3f2e2d4defd508fdb9a051bceab7ec3faea734e6f8de25125da70c6/image-20240424-130029.png?cb=eb77673d263402039305cc937bfcb9eb) Note how the components are used to re-create the tree defined above. Note also how the various parameters and export elements used in the widgets are referencing the names of existing parameters of the definition, used to control the core algorithm. See the corresponding App [here](https://www.shapediver.com/app/builder/v1/main/latest/?slug=240424-appbuilderfirstexample). ![image-20240424-131635.png](https://help.shapediver.com/__attachments/a_3595f6770b6b562062b3f21bb389d1b4ec0c2291f12d2b077a9d9bd4ad5a4ba0/image-20240424-131635.png?cb=659a08651df6197a806f238cbe72a698) At the moment, the first App Builder template only accepts containers with the names "left", "right", "top" and "bottom" (see section below). The names of containers in the definition above follow this scheme instead of the names "Parameters" and "Results" of the tree. **Parametric interfaces** Since the skeleton is controlled through Grasshopper, it can be parametric and depend on the state of the associated model. This allows to do such things as: * Update the layout of the application depending on user inputs * Only show relevant parameters and hide the unused ones in the current state * Use widgets to display data, graphs, images and more that reflect the current state * And much more... As an example, consider the following definition: ![image-20240424-102416.png](https://help.shapediver.com/__attachments/a_341bb6b523e9cfa96e470f04a41f5b723959d40d9f5f030b8656c73f82f58f6e/image-20240424-102416.png?cb=b6300aba24e3c2b4c596babd258cec3f) Through the "Select Box" toggle and a stream filter, one is able to control the contents of the "right" container to either show the "Box 1 Size" parameter or the "Box 2 Size" one. See the corresponding App [here](https://shapediver.com/app/builder/v1/main/latest/?slug=240424-appbuilderswitchparam) (using the default template). ![AppBuilderSwitchParam.gif](https://help.shapediver.com/__attachments/a_050b283ea8489ff1c23cfc3d56c258f67637414258b62e6ba63aab12974e0204/AppBuilderSwitchParam.gif?cb=ef847bf5ffc7ffac99d31c8166d34820) Read more about the App Builder components and their various options in the plugin's [App Builder section](https://help.shapediver.com/doc/app-builder.md). ## Connect to a specific template Grasshopper definitions including App Builder components only contain information about the skeleton but no information on how to translate the logic and information of the skeleton into a concrete layout on a device's screen. In the example above, the application contains two containers (Parameters and Results), but it does not say where to place those containers on the screen, with which dimensions, or what happens on mobile screens, among other considerations. A *template* is a pre-defined layout that implements a specific organization and set of rules to interpret a skeleton on a screen. A template will typically look for a specific naming scheme in the skeleton (names of containers, tabs...) and execute a specific behaviour when it finds the associated name. For example, a specific "Furniture App Template" could always expect a container named "Parameters" and display it on the left of the screen, with a width of 300px, and a container named "Results" and display it on the right. At the moment, ShapeDiver includes a first default template that expects four container names ("top, "left," "right," and "bottom") and interprets them in a flexible, responsive layout. Here is how the default template is organized on a desktop screen: ![image-20240502-083633.png](https://help.shapediver.com/__attachments/a_f2a68960333c4be2d70e08844235ac6376072d07b0974916d8bce1d569dde3f1/image-20240502-083633.png?cb=ea97eacb89a62a09d828503c5c4a4578) This layout is responsive and adapts to various screen sizes and depending on the visibility of the various containers defined in Grasshopper. In the initial phase of App Builder, the layout rules of the default template will evolve frequently. We will document them in more details once they become final. Additionally, more templates will be developed in the future, covering different use cases. ## Themes and styling options The layout defined through a template still does not contain information about the last layer of the web application: styling. Things such as the colors of various elements, the font settings, and other properties that web developers usually control with CSS can still be modified without affecting the layout. Each App Builder template comes with a theme, which provides default values for these styling options. However, it is always possible to customize the theme according to one's tastes or a company's specific branding. Read more about how to customize a theme in [this article](https://help.shapediver.com/doc/customize-a-theme.md). The ShapeDiver platform will include a theme editor in the future as a user-friendly way to customize themes. For now, the associated article describes a workaround that already allows full control over the theme's styling options. --- language: "en" --- # Container ## Overview Use the *Container* component to define "ShapeDiver App Container" objects. Containers are the top-level building blocks in the skeleton of a ShapeDiver App: you define an App with several Containers, and each Container can include one or more child parts ([*Tabs*](https://help.shapediver.com/doc/build-tab.md) and [*Widgets*](https://help.shapediver.com/doc/widget-components.md)). Read more [here](https://help.shapediver.com/doc/build-apps-in-grasshopper.md)about the App Builder and how you can use it to drive web applications from Grasshopper. Use this component to create static containers that occupy a docked space on the screen and restrict the size of the viewer canvas. To create containers that float on top of the viewer canvas, use the [Floating Container](https://help.shapediver.com/doc/floating-container.md) component. ## First example For example, create a container named `right` that contains two tabs named `Geometry` and `Materials`: ![image-20241016-084123.png](https://help.shapediver.com/__attachments/a_d45e7903148e470b6bcace7aa78b924542a6b0d8a0436f52d9a6b056746fa9d9/image-20241016-084123.png?cb=203aa6ea2144343b7bad7093c551e21c) The template you use determines how the ShapeDiver App displays this configuration. In the default template, the desktop layout looks like this: ![image-20240502-084615.png](https://help.shapediver.com/__attachments/a_c7bccff2e55f8b74cf21f658c1f5feef6d0eb279d7f00cf95e6d68dd7acba81e/image-20240502-084615.png?cb=e79168661f4ed3edf8d7bf6f1f288a4f) ## Properties Define a "ShapeDiver App Container" object with three properties: * A *Name* that identifies the container. Use any name, but note that some ShapeDiver templates might require specific names to build their layout. For example, the default template accepts four reserved names: `top`, `bottom`, `left`, and `right`. * A list of *Tabs*. * A list of *Widgets* to include in the container. Both Tabs and Widgets are optional inputs, but you need to define at least one of these inputs for the component to create a valid container. ## Tabs or Widgets As a general rule, use tabs as an intermediary building block between containers and widgets. However, you can define widgets directly inside containers in the following use cases: * You do not need to organize the container contents into separate tabs. * You need to display one or more widgets regardless of the currently active tab. In the default template, widgets included directly in containers are always displayed at the bottom. ## Outputs Connect the "ShapeDiver App Container" object to the [App](https://help.shapediver.com/doc/build-app.md) component. Define an App with a list of Containers. --- language: "en" --- # Image Widget ## Overview The *Image Widget* component can be used to include images in the layout of Apps created with the [App Builder](https://help.shapediver.com/doc/app-builder.md) components. Like other Widgets, Image Widgets can be included inside [Tabs](https://help.shapediver.com/doc/build-tab.md) of the App, or directly into [Containers](https://help.shapediver.com/doc/build-container.md). Images can either reference a public URL or an Export component in the definition which contains a parametrically created bitmap. ## Referencing a public URL Use the "URI" (U) input of the component to specify a publically available location where the image you want to include is stored. Consider the following definition: ![image-20240731-153015.png](https://help.shapediver.com/__attachments/a_90f74f7b61e2c9f79e10b455b0469c1dc865eec134464e53cbe3ea39f0dc4e11/image-20240731-153015.png?cb=99ba1513d970ca61db6a260969d8a826) Using the default template, it defines a simple application with one right container, which includes an image widget with the specified URL. The application looks like this: ![image-20240731-153337.png](https://help.shapediver.com/__attachments/a_77ee1b7f322b1fe6d58b8118c3f79311bc3c212df5e4437a1071fdc520c0421e/image-20240731-153337.png?cb=618a582fe8d4b49ffc930ad6a0a0e79f) Note that the viewer container is empty because the definition does not define any display geometry. ## Referencing an Export component The ShapeDiver plugin allows the manipulation of bitmap objects directly in Grasshopper by means of [specific components](https://help.shapediver.com/doc/images.md), the [Squid plugin](https://help.shapediver.com/doc/squid-shapediver-edition.md), and other third-party plugins like [Bitmap+](https://www.food4rhino.com/en/app/bitmap). Once a bitmap object is created in the definition, it can be displayed in the Image Widget by means of a [Download Export](https://help.shapediver.com/doc/download-export.md) component. Essentially, the *Download Export* component exports the image in the web application's background and shows it directly in the interface. In order to make the connection, simply reference the name of the Export component in the "Export Name" (E) input of the component. Consider the following definition: ![image-20240731-160949.png](https://help.shapediver.com/__attachments/a_c36bb2cee3c343766d7ebf698f4099ab38f2a977cef072469aa7fc4da4b13759/image-20240731-160949.png?cb=cde287dc3029db65802f9f3da1577e96) First, we create and display a box in the viewer. Second, we project the box with the *Make2D* component and draw a bitmap using the Squid plugin. Third, we use the *Download Export* component to export the bitmap to a jpg. Finally, we reference our *Download Export* component (called "Projection" in the example) in the "Export Name" (E) input of the *Image Widget* component. The final application looks like this: ![image-20240731-161324.png](https://help.shapediver.com/__attachments/a_f160c8dce7a7d01177347c186924ab054696e90ca87c8c9c0a10068628d15fd0/image-20240731-161324.png?cb=6e7ab9f6c4502f147ff50b19de99cac7) [Download](https://shapediverdownloads.s3.amazonaws.com/DemoModels/11-AppBuilder/AppBuilder_ImageWidget_Export_Tutorial.gh) the Grasshopper definition of this example. Extra credits are spent when using the Export components. Read more information about export requests and the credits they incur [here](https://help.shapediver.com/doc/credits.md). ## Specify an image description Use the "Description" (D) input of the component to add a description to the image. This description is used to generate the `alt` property of the image in the web application. Read more about this topic [here](https://www.w3schools.com/tags/att_img_alt.asp). ## Add a link to the image You can make the image clickable by specifying a URL in the "Link" (L) input of the component. Users of the App will then be able to click on the image to follow the specified link. Additionally, use the "Target" (T) input to specify what happens when clicking on the image. By default, the target is `_blank`, which means the link is opened in a new tab of the web browser. ## Sizing Depending on the template you are using, the image will be sized for the best possible fit in the layout. If you are using the default template, images in the `left` and `right` Containers will be resized to fit the width of the containers and keep their original ratio. Images in the `top` and `bottom` Containers will be resized to fit the height of the containers and keep their original ratio. --- language: "en" --- # Tab ## Overview Use the *Tab* component to define a "ShapeDiver App Tab" object. Tabs are one of the elements you can include inside a [Container](https://help.shapediver.com/doc/build-container.md), along with [Widgets](https://help.shapediver.com/doc/widget-components.md). Use tabs to divide a container into sections that users can browse through a tab menu. Depending on the template you use, tabs can also translate into another layout style. Read more [here](https://help.shapediver.com/doc/build-apps-in-grasshopper.md)about the App Builder and how to use it to drive web applications from Grasshopper. ## Inputs The Tab component accepts four properties: * **Name**: A name identifying the tab. If you do not specify a name, set an icon. * **Icon**: An optional icon displayed next to the tab name in compatible templates. * **Tooltip**: An optional tooltip displayed when users hover over the tab. * **Widgets**: A required list of widgets to display when this tab is active. Provide at least one widget to create a Tab object. As an example, the following definition defines a tab named `Pictures` with the icon `camera`, a tooltip saying "A list of images." and containing two widgets (one [Controls Widget](https://help.shapediver.com/doc/controls-widget.md) and one [Image Widget](https://help.shapediver.com/doc/build-image-widget.md)). ![image-20260612-125014.png](https://help.shapediver.com/__attachments/a_34f37e0c82280f3c98ce5fcc4f870bc889f2e20fa82038f2e0f76dfe0c46c283/image-20260612-125014.png?cb=b158ed00f4b6be4c2282cf6e35a6742e) ## List of available icons ShapeDiver Apps use the [Tabler icon library](https://tablericons.com/). Search for an icon and use its exact name as input to the Tab component. --- language: "en" --- # Text Widget ## Overview The *Text Widget* component lets you add a text panel to the layout of apps you create with the [App Builder](https://help.shapediver.com/doc/app-builder.md) components. Like other widgets, you can place Text Widgets inside [Tabs](https://help.shapediver.com/doc/build-tab.md) of the app or directly inside [++Containers++](https://help.shapediver.com/doc/build-container.md). The component supports plain text and GitHub-flavored Markdown, plus a ShapeDiver-specific extension for colors and formatting styles that standard Markdown does not include. The component has one text input and outputs a widget that you can add to the app's layout. ![image-20240801-103103.png](https://help.shapediver.com/__attachments/a_29cb96d4e5dd5d28715d625ff4e1d78f7aa06552f7ca49d9076685b7f040547d/image-20240801-103103.png?cb=7c65a19d062c005e16646f9f6a22b223) ![image-20240801-103124.png](https://help.shapediver.com/__attachments/a_93ddde44058a09932a27c40c144f4c28abc0877c1c38d67b197fd907baa71196/image-20240801-103124.png?cb=d861989c16d1a6876782cfdd1fa04c0c) In this example, the viewer container stays empty because the definition does not specify display geometry. ## Markdown syntax The text widget uses GitHub-flavored Markdown. You can find the full list of formatting instructions [here](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). The examples below show some basic Markdown syntax: `# This is a H1 heading.` `## This is a H2 heading.` `This is normal text.` `*This is italicized text.*` `**This is bolded text.**` `* This is a bullet point.` `This is [a link](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax).` ![image-20240801-101501.png](https://help.shapediver.com/__attachments/a_63529363751fa80c02021e41c1a418bfedf76ea029dad98c97258cb362a6eb6b/image-20240801-101501.png?cb=7f0fa7889f0f9d29f9bb10324f486837) ## Table formatting You can use the Markdown version that the component supports to format tables in text panels. ![image-20240801-102618.png](https://help.shapediver.com/__attachments/a_b478809d6c7702c63e858385e1c00c9788878f3c5c2d36835c7eb1b500ee7a6b/image-20240801-102618.png?cb=acce4c7e3b30607a3c05101f47070234) ![image-20240801-102637.png](https://help.shapediver.com/__attachments/a_269d7e7677475f69ae796dbe467096d11992cb439cc53e70e11d9c310ddacbfe/image-20240801-102637.png?cb=86c47d4fa8fe30d7170cf5d486a8aa03) [Download](https://shapediverdownloads.s3.amazonaws.com/DemoModels/11-AppBuilder/AppBuilder_TextWidget_Tutorial.gh) an example Grasshopper definition that includes a cluster you can use to format tables for the text widget. ## Text formatting with the ShapeDiver extensions You can use the following syntax to format part of a text: `This is how to color :span[some words in blue]{color="blue"}.` ![image-20240801-094841.png](https://help.shapediver.com/__attachments/a_387a7748d7bfe87fc7ae5facc2a77e6a1acc01df521ea28e19c586ed186f6171/image-20240801-094841.png?cb=f43a1fab5cb39a567306e8fd75bdf1e1) You can use the extension to color text and apply subscript, superscript, and underline formatting: `:span[This is subscript.]{style="sub"}` `:span[This is superscript.]{style="sup"}` `:span[This is underlined.]{style="ins"}` ### Color extension You can specify some primary colors by name, such as "blue" in the example above. Alternatively, you can specify any color with its hexadecimal representation: `Use a hashtag in front :span[of the hexa code]{color="#E233F3"}.` ![image-20240801-095201.png](https://help.shapediver.com/__attachments/a_991b2641da01f6c4ab26928fa881f34bdd0570e573023daf27dbd514d0ebd4e0/image-20240801-095201.png?cb=faf4b25fe90c52ff396a72c766581c34) You can combine the extension with other Markdown instructions: `*:span[This is italic text.]{color="green"}*` ![image-20240801-095402.png](https://help.shapediver.com/__attachments/a_f9922680263c6ec80dfa65deba807d4bb2b53c10c4fcab4ba3c76fb687a6ca0d/image-20240801-095402.png?cb=cff50c801f4da62f1c2cc90a96f2a1e4) ShapeDiver may extend this syntax in the future to support additional Text Widget formatting options. --- language: "en" --- # Building ShapeDiver Models * [Defining inputs](https://help.shapediver.com/doc/inputs-and-outputs.md) * [Defining outputs](https://help.shapediver.com/doc/defining-outputs.md) * [Ordering and grouping parameters](https://help.shapediver.com/doc/ordering-and-grouping-parameters.md) * [Forbidden Grasshopper functionalities](https://help.shapediver.com/doc/forbidden-grasshopper-functionalities.md) * [List of forbidden Grasshopper components](https://help.shapediver.com/doc/list-of-forbidden-grasshopper-components.md) * [Limitations regarding definition outputs](https://help.shapediver.com/doc/limitations-regarding-definition-outputs.md) * [Supported third-party Grasshopper plugins](https://help.shapediver.com/doc/supported-third-party-grasshopper-plugins.md) --- language: "en" --- # Camera settings By default, a ShapeDiver model includes a set of default orthographic cameras (Top, Bottom, Left, Right, Front, Back) and a perspective camera. Users in the model view page and Apps can switch between them using the Camera button on the viewer canvas: ![image-20231204-143707.png](https://help.shapediver.com/__attachments/a_cc5b4acfaac32ab2633e558f37af7f39f9c0e5b4ea5e5f6a956a968fb8d5de8d/image-20231204-143707.png?cb=50ea6a330b97359257cdab8a2b6573bf) The Camera settings panel can be used to: * Hide or show the default orthographic cameras. * Add or remove other custom cameras in the scene. * Edit the settings of each custom camera added to the scene. ## Disable default cameras Use the toggle at the top of the section in case you would prefer hiding the default orthographic cameras from the canvas menu. If you enable this, only the cameras defined below in the settings panel will be shown in the model/App. ## Custom cameras After uploading a model, the viewer automatically includes a first custom camera called "Perspective". It is possible to create other custom cameras and add them to the scene. In order to do this, click on the "+" button at the top of the section. A dialog opens, allowing to define a name for the new camera, as well as its type: ![image-20250716-102825.png](https://help.shapediver.com/__attachments/a_eaa7c72dfbec3f67bd1bfdae0c86fd36f62f08a08076a4cdd06045cafab5b1ab/image-20250716-102825.png?cb=d838d88e9ab00817e6e3422a7f308789) After clicking on Save, the camera is added to the scene. Specific settings of the camera can be further edited by unrolling the corresponding accordion menu. Note that at least one custom camera needs to be present in the scene. As a consequence, a custom camera can only be deleted from the list if at least another one is present. Additionally, a camera can only be deleted if it is not currently active in the viewer (selected, blue accordion): ![image-20250716-103135.png](https://help.shapediver.com/__attachments/a_18d8cf406bd10e3033e35a5544ab1abd324e7b7029e4b9c45bbf77d358a0d600/image-20250716-103135.png?cb=46f80c416921eed35aaa25f738ab1ce6) ## Edit a single camera ### Renaming Use the context menu of a specific camera to rename it. The name of the camera is the one that will help users identify it in the list of options of the viewer: ![image-20250716-103358.png](https://help.shapediver.com/__attachments/a_9549c5e5bf6d6a3ce05fe60e5b5960d2342a0bb3771a1481b2dd7f3e1ef6ccfe/image-20250716-103358.png?cb=122f189fff3b21a4ab0839fc27f0fc8c) ### Editing the position In order to edit the default position of a specific camera, make sure it is the currently active one in the viewer (radio button selected). You can then update the position in the 3d scene by zooming, panning and rotating as desired. Once the camera is in the desired position, you will notice a reload button appearing on the corresponding accordion menu: ![image-20250716-103545.png](https://help.shapediver.com/__attachments/a_b9a92b817c01030e6793bbb82d6ce68454741b782f6d66d3622753e6d6b9e204/image-20250716-103545.png?cb=8f8e2e44fdae40b0526825d4b168137d) Click on this button to update the associated default position of the camera. Like for other camera settings, make sure to save the model afterwards in order to apply the setting. The first time you edit your model (right after uploading it to the platform), clicking on Save will automatically use the current position of the active camera as the default one. ### Editing other camera settings In order to update the configuration of a specific camera, unroll the accordion element to list the options attached to it. Find the list of options below. | **Option name** | **Description** | |------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | View | Switch between a perspective camera or one of the orthographic preset options. | | Field of view | Camera frustum vertical field of view, from bottom to top of view, in degrees. | | Disable zoom | Enable or disable zooming in the viewer when scrolling (desktop) or pinching (touch screens). | | Zoom speed | Speed of the camera movement during zooming interactions. Normalized value between 0 and 1. | | Disable pan | Enable or disable panning in the viewer when dragging with the right mouse button (desktop) or three fingers (touch screen). | | Pan speed | Speed of the camera movement during panning interactions. Normalized value between 0 and 1. | | Disable rotation | Enable or disable rotations in the viewer when dragging with the left mouse button (desktop) or one finger (touch screen). | | Rotation speed | Speed of the camera movement during rotations. Normalized value between 0 and 1. | | Auto rotation | Define the direction and speed of the camera auto rotation. By default, the camera does not autorotate (value 0). Negative values triggers a clockwise rotation around the Z axis while positive values define an anti-clockwise rotation. The speed is controlled by the amplitude of the value. | | Damping factor | Define how fast the camera movements are attenuated after a camera movement (zoom, pan, rotation). Lower values of the damping factor imply long residual camera movements after interactions while higher values cause the movement to slow down and stop faster when the mouse or touch is released. | | Zoom factor | The distance between the camera and its target (by default the center of the scene) will be multiplied by this value. | | Camera adjust | When changing parameters, the scale and position of the objects in the scene can change significantly. When this setting is active, the camera automatically adjusts the position and target of the camera after parameters are changed. | | Adjust duration | Duration (in milliseconds) of the camera movement after the camera is adjusted (automatically if "Camera Adjust" is active or through an update call). | | Camera revert | When this setting is active, the camera will return to its default position after any mouse or touch interaction with the viewer. | | Revert duration | Duration (in milliseconds) of the camera movement after the camera is reverted. Only used when "Camera Revert" is active. | | | | --- language: "en" --- # Chart Data Series --- language: "en" --- # Chart Data Set --- language: "en" --- # Chart Widget Components * [Area Chart Widget](https://help.shapediver.com/doc/area-chart-widget.md) * [Bar Chart Widget](https://help.shapediver.com/doc/bar-chart-widget.md) * [Line Chart Widget](https://help.shapediver.com/doc/line-chart-widget.md) * [Round Chart Widget](https://help.shapediver.com/doc/round-chart-widget.md) * [Chart Data Series](https://help.shapediver.com/doc/chart-data-series.md) * [Chart Data Set](https://help.shapediver.com/doc/chart-data-set.md) * [Round Chart Data](https://help.shapediver.com/doc/round-chart-data.md) * [Plot Settings](https://help.shapediver.com/doc/plot-settings.md) --- language: "en" --- # Chromatic Aberration Chromatic aberration is a post-processing effect commonly used in computer graphics and video games to simulate a lens aberration that occurs in real-world cameras and lenses. It introduces a color fringing effect around the edges of objects, caused by the different wavelengths of light being refracted at slightly different angles as they pass through a lens. [Postprocessing Package Reference](https://pmndrs.github.io/postprocessing/public/docs/class/src/effects/ChromaticAberrationEffect.js~ChromaticAberrationEffect.html) *** ** * ** *** ## Properties | **Name** | **Descriptions** | |--------------------|-------------------------------------------------------------------------------------------------------------------------------------| | `BlendFunction` | How the original image and the effect are blended together, in most cases it does not make sense to deviate from the default value. | | `modulationOffset` | The modulation offset. Only applies if `radialModulation` is enabled. | | `offset - x` | The effect offset in the x direction. | | `offset - y` | The effect offset in the y direction. | | `radialModulation` | Whether the effect should be modulated with a radial gradient. | --- language: "en" --- # Clear cached assets ## Context When sending computation requests to the ShapeDiver servers (for example, by updating parameters or requesting exports in the model view page of your model), our caching system remembers the results of each computation, in order to send the solutions faster the next time a specific request is sent again. Those further times the same request is placed, it does not reach the computational server instances (running Rhino and Grasshopper), rather it pulls the results directly from our caching system, which makes the transaction much faster. For various reasons, you might want at some point to bypass the caching mechanism and force your models to recompute a new solution. These reasons include, but are not limited to, the following: * One or several computation requests for the model failed. This might have happened because of timeouts or any limit associated with your account being hit. In case you upgrade your account to raise those limits, you can empty the cache of your models and send the requests again. * You have updated some files from your own servers or other online location (images, CAD files, text files, etc...), and these files are referenced through their URL in your model. In that case, our system has cached the solutions associated with these URLs and emptying the cache is necessary to reflect the changes from your side. * Your algorithms are non-deterministic and you would like to produce different random solutions. * ... ## Clearing the cache At the moment, it is not possible to disable the caching mechanism permamently for models, but the platform lets you empty all cached assets associated with specific models of your library. This functionality is available in two locations. ### Model edit page Find the button to clear the cache on the top right of the viewer canvas in the model edit page: ![image-20221212-094243.png](https://help.shapediver.com/__attachments/a_73037040bb1549b3c09b1db70afb1c9f0f2f258713fc61ceb479ebd61a111790/image-20221212-094243.png?cb=99cbfd13b0b264720cbf4b2a1f1eb678) ### Model library From the model library listing, find the option in the context menu (card mode) or in the list of actions from the table view: ![image-20221212-094537.png](https://help.shapediver.com/__attachments/a_b3ca60f11a61c11df3150c3f39f96f7c435c13a3c351687161299c34800d0cef/image-20221212-094537.png?cb=f04bb2951f414643b61aa66b0fc422d8) ![image-20221212-094612.png](https://help.shapediver.com/__attachments/a_acc2a60d7e374d13486cca9fb3005aa80572a78a080865058b5ca741179a1c9c/image-20221212-094612.png?cb=6b537dfc40566f7f043fce4e53ba9a01) ## Caching options ![image-20221212-094657.png](https://help.shapediver.com/__attachments/a_1c762f34c3cfc19d1d152e20902599325d7db00793d23121f112d9c2c54b138e/image-20221212-094657.png?cb=df1e9fa3545d0f7a197caee61ca2b8ee) There are three types of assets associated with your models which can be wiped from the cache: * Outputs: Any of the display outputs from your definition (any component with the preview on in Grasshopper generates glTF asset to be displayed in the viewer), as well as any data coming through ShapeDiver Data Output components. * Exports: Any file exported from your model using the Download Export or Email Export components from the plugin. * Textures: Any texture used for the materials of the displayed geometry that was previously loaded in the viewer. You can choose to wipe any or all of these assets separately. Clearing the cache is an operation that can take up to a minute. Once the operation is started, the assets for which the process is in progress will display a progress bar. Leaving the dialog will not interrupt the process, you can come back later and check if the operation is still in progress. When it is done, the options become available again. --- language: "en" --- # Clear the cached assets of a model Every time someone interact with a ShapeDiver model and receives results (from the ShapeDiver platform, a desktop client or a custom application using the API), the results are cached in the ShapeDiver servers. Cached results can be requested much faster that newly computed results, making it an important aspect of ShapeDiver's performance, in particular when using such features as [saved states](https://help.shapediver.com/doc/saved-states.md) and [importing/exporting parameter values](https://help.shapediver.com/doc/parameters.md). Three types of assets associated with ShapeDiver models are cached on the servers: * Image files used as textures within the material definitions of the displayed geometry * The various outputs generated for each solution of the model, including the geometry that gets displayed in the ShapeDiver viewer and data outputs. * The export files requested through the export components of the plugin. For various reasons, you might want to punctually clear some or all of the cached assets listed above from your ShapeDiver model. Such reasons might include the following: * One or several computations associated with the model has failed (connectivity issue, the computation took tool and reached your computation limit, etc...) * You have updated the URL of some imported images that you use as textures for the model. In this case, you can use the "Clear cache" option of the model, which is available in three locations: * As part of the model card context menu * As part of the "Actions" column of the library's table view * Above the viewer in the model edit page The "Clear cache" option opens a dialog: ![image-20230707-100801.png](https://help.shapediver.com/__attachments/a_dabdafdf1f7a21393d1d94add8bc1033fc23f57c42f29b16ca1ea6a9925e0c8a/image-20230707-100801.png?cb=4bad3c0647d9a9ebffd1b332c32650e6) The dialog lets you pick any or all of these 3 asset categories for cache clearing. Once you click on "Confirm", the operation will start. Clearing the cache might take a while, but you can close the dialog without interruping the operation. [Next Page](https://help.shapediver.com/llms-full.txt/1)