CSR Editor Tutorial¶
Important Disclaimer¶
The project is currently in alpha state. There will be bugs, new features to be added and workflow improvements based on feedback. If you want to report an issue, or request new features, you can create an issue in the repo (to be created).
Missing features to be added:
- 2D Fonts;
- Patches support;
- Animation support, with support for starting animation;
Purpose of the Editor¶
The process of creating CSR (client-side rendering) builds can be daunting, as Three.js, the engine that is used to power the rendering, is extremely customizable. The complete look of the materials, camera positioning, lighting, can be controlled, but builds need to follow specific specifications to ensure all CSR builds work properly with existing PlatformE technologies.
To ease the creation of a full CSR build across several members of a team, and ensure the client knows the final look of a product, an alternative needed to be created. It needed to allow artists to have full control of the scene in an interactive way, while ensuring they never needed to worry about following very detailed specifications, as it was being done automatically behind-the-scenes. This is the purpose of the CSR Editor.
How to Access¶
The CSR editor is currently live on this site, so if you want to follow along the tutorial, you can use the link provided.
Getting started¶
Interface¶
When you open the site, you'll be faced with a 3D grid, with some menus, along with a menubar on top. The menubar contains few items, with the only important one for the tutorial being the RIPE
tab. This allows you to restart your current build from scratch, export the current state to a zip, and import it back.
If you export the current state of the project, a build.zip
file will be created, containing all the textures, fonts and configurations organized neatly. If you want to send the entire state of the project to another colleague, you can send the compressed file, and on the target browser select Import 3D Build Zip
, and all the information will be transferred and auto-populated. You can use the zip
file almost as a form of versioning a CSR build, if you would so desire.
If the autosave
checkbox in the upper-right corner is selected, the state of the entire RIPE project will be stored, and you can safely reload the page without losing any progress.
On desktop mode, on the right-side of the screen we have multiple tabs, with each of them grouping a specific part of the pipeline. Since each tab has some complex logic within, each tab will be explained in more detail in their respective section.
Basic Viewport Controls¶
Here are the basic ways to interact with the viewport:
- Rotate the viewport by panning the mouse while pressing
Left Mouse Click
; - Zoom in or out through scrolling
Middle Mouse Wheel
, or pressingMiddle Mouse Click
and panning up and down; - Pan around the scene by panning the mouse while pressing
Right Mouse Click
; - Rotate to an axis by pressing the respective axis in the bottom-right corner of the viewport;
If you have an object selected, a helper will pop-up to assist with moving around the scene. If you want to add a simple plane, without needing to have a full model, go to the Lighting
tab, and click on the NEW
button to create a shadow plane. After that, here are the basic shortcuts to control the object:
- Press
W
or click on the axis symbol in the top-left corner of the viewport to move the object around; - Press
E
or click the circle arrows in the top-left corner of the viewport to rotate the selected object; - Press
R
or click on the expanding arrows to scale the object; - If you want to perform any of these actions in the object's local axis, tick the checkbox in the top-left corner of the viewport.
In the top-right corner of the viewport there's a small dropdown list to select the viewport camera, which can be the default camera, or the RIPE Camera. We will go into more detail about this in the Camera section.
Assets¶
Now that we know how to basics of interacting with the viewport, we can begin creating a RIPE CSR build. The base building block of the build is the mesh of the product.
To import a model (glTF is by far the preferred format), click on the import model button, and select the specified mesh. After clicking, the mesh should be now in the center of the viewport, only completely black. This is due to there being no light in the scene. We can add an HDRI to light up the scene, or we can add a light.
If we do use an HDRI, we can use that image as the environment map, as well as the background for the build. If you instead want to use a flat color for the background, all that's needed is to un-tick the Use HDRI as Background
, and that configuration will be stored in the build.
The next important part to keep in mind is the concept of Mesh Groups. This is the system CSR uses to detect when there are bundles of meshes. This is easily understood with an example. Imagine the product of the build is a watch, which has several parts and meshes. However, there are groups that always share the same material, like the bracelet and buckle. We would want to group these meshes, so that with one request, the two meshes would change the material. For this reason mesh groups were created, to allow for simpler builds with less specific rules, while still maintaining the flexibility of mesh bundles.
To create a mesh group, all that's needed is to click on the Add Mesh Group
button, and a new element will appear. With this you can map a single name (like bracelet
) to the individual meshes.
If you want more information about how to prepare a mesh for CSR, please read that document in the tutorials page!
Materials¶
The next major step in creating a fully customizable 3D Build for CSR comes with materials. There's an entire tab dedicated to this part of the process, but before we go through the interface, there's an important note about default materials.
Contrary to normal Pre-Render Compose (PRC) builds, in which sometimes a part
could actually contain several meshes, for CSR every single mesh needs to have a material. Returning to the watch example, one great way to visualize this is by thinking about the glass. In PRC, it's just glass, and is not a part in itself, appearing in the case images. However, for real-time rendering, a material needs to be assigned to the glass mesh, otherwise it's an opaque grey material. The problem lies in the fact that the glass is not a specific component of the build specification, just a mesh that exists in the product.
To allow for meshes to have a material while not being a part of the build, we have default materials. This is the material that is used as the fallback for a particular mesh group. It can't be deleted, as it's considered to be "static", i.e. not customizable. In the watch example, the glass mesh would have a material that allows for transparency, and that information would be stored in the CSR specific portion of the build. With that information, let's see each component of the material interface.
Firstly, there's a quick reset parts button, which deletes all added materials, and resets all the default materials to their base state.
If you want to add a new material, you have to specify the material and color name, to comply with the standard PlatformE naming conventions. When clicking the Add New Material
button, the selected part below will have a new material with the specified color. The dropdowns below will reflect that, auto-selecting the newly added material. You can delete the added material, or just a specific color. If a material has no associated colors, it will also be auto-deleted to prevent accidentally having empty materials.
If you want to edit a material for a specific part, click on the Edit Selected Material
button. The UI will change to the properties of the material being selected.
In the new menu, you can tweak all the specific properties of the selected material. If you want to disable a texture, you can un-tick the checkbox right next to the texture you want to change. If you try to export a zip containing disabled maps, these will not be stored in the final file, nor will they appear in the configuration. This is meant to prevent the user from accidentally exporting maps that they specifically disabled.
And that's all there is to it! Create your materials, one by one, taking into account that the material and color name will be the ones the build is already looking for. The visual result in the editor will be the same as the final CSR build!
Lighting¶
After the mesh and materials are created, comes the lighting setup! We have multiple light types available, namely:
- Ambient Light: Uniform light throughout the entire scene, no shadows;
- Hemisphere Light: Light that simulates a sky, has a color and a ground color. Position controls falloff point;
- Point Light: Standard point light, rotation is irrelevant, casts shadow;
- Directional Light: Simulates Sun Light, with relatively narrow shadow areas;
- Spotlight: As the name suggests, a spotlight. Can control several aspects of the light, such as penumbra and angle;
- Area Light: Standard area light, provides even lighting for a specific area, can't cast shadows;
To create a light, simply click on the respective button, and a new element will appear, letting you control the added light. To delete a light, you can click the DEL
button on the light, or you can choose to delete all lights by clicking the Reset All Lights
button.
Another major factor for good lighting is a good shadow. However, in real-time it's quite hard to get the same results as a ray-traced renderer. For this reason, a shadow plane can be created, which can hold a texture. This plane can be moved, scaled and rotated at will. The opacity for the shadow plane can also be tweaked, to create a softer or more opaque look without requiring the artist to re-bake the shadow, or re-paint the shadow in another application.
The shadow resolution is a general setting that automatically applies to all the lights in the scene, whereas the shadow bias is a property that is better used when finetuning the look of a particular light to avoid potential artifacts.
The Toggle Helpers
checkbox toggles all assistants, including the grid, to allow the user to have a stronger impression of what the final result will look like.
With the lighting setup completed, next we move to the camera setup.
Camera¶
The camera tab contains all the information that is required to allow for fine control over how the particular product will be displayed.
Here's a list of what each property does, and how it affects the final camera system:
- Allows Scroll: Whether the user can scroll or not. If is allowed, two more elements, minimum and maximum distance, will appear. These are the maximum and minimum bounds for zoom you that allow to the client;
- Starting Distance: The default distance of the camera to the product. This is what will be used as the starting distance, as well as the fallback, for when the user selects a specific view, for example;
- Horizontal and Vertical Locks: Determines whether the user can pan vertically or horizontally respectively;
- Starting Horizontal and Vertical Angle: Similar to the base starting distance, these will be the angle at which the product will be presented when entering the new page;
- Target Position: The X, Y and Z coordinates of the "center" of the object. This will serve as the pivot, and rotations will be around this point;
- Horizontal and Vertical Constraints: Checkboxes that if ticked, will let the user select the upper and lower bounds for the angles to be displayed. This is useful for specifying the ranges of angles the brand wants to show a particular product, in case they don't want "full" 3D rotation;
- Camera FOV: The field of view for the camera.
It would be difficult to implement these changes without looking at what we would be changing, so for this reason there's a button up top that initially says Test Camera Settings
. When clicked, this will activate a special RIPE camera, that holds the properties being specified. Use this to test out any setting in real-time, and have a granular control over the final look of the camera.
Personalization¶
The only remaining aspect to talk about is the personalization. Currently we only support initials placement, but patches will also be supported in the future.
To access this feature, click on the Personalization
tab. For this part of the process, we can begin by either loading a font, or by placing the initials. We will explain each separately, since they can be done in parallel.
For loading the font, click on the Load Font
button, and add either a .ttf
or a .JSON
font file. The latter is the correct format for 3D fonts, while the former needs to be converted before being able to be used. After that, the Selected Font
dropdown now features the added font. Only after this step can materials be created.
Regarding placement, there are some extra steps needed. Firstly, the number of initials needs to be set. For this, the Num. Initials
number field needs to be different than 0, then click the Recreate
button. This will generate the given number of initials, destroying the previous placements in the process. If you want to alter the spacing, change that property, but it will also complete recreate the placements.
The size of the initials, as well as the text thickness can be updated without destroying the position and rotation aspects of a letter.
To ease the process of placing the guides, you can toggle the X-Ray
feature. This will make the guides appear in front of all geometries. If you want to test how the text will appear, if you have a loaded font, you can add text in the Text Test
input field, and the text will appear on the guides, with the given material. If you want to check how the text would look like without guides, you can toggle them with the Show Guides
checkbox.
If you would like to add a more custom material, you can do so by adding the name and color of the material, and press the Add New Material
button. A new UI panel will appear, to give you finer control of each material. These materials will be stored in the final configuration file, as we currently don't have texture support, since fully generated 3D Fonts have UV problems. 2D fonts will be added in the future.