User Guide & Reference
Sundari Documentation
Straight-to-the-point guide on how to do common tasks, what every setting means in plain English, and all keyboard/mouse shortcuts.
How to Do Common Tasks
1. Open a Scene
- By default, Sundari launches with a clean empty scene. Try loading the bundled sample scene via File → Open Simple.ssd.
- Press ⌘O
(File → Open Scene...) and select any
.usd,.usda,.usdc,.usdz,.mtlx, or.ssdfile/folder. - Or simply drag and drop
a scene file or
.ssdfolder directly from macOS Finder onto the Sundari window. - To clear the scene and start fresh, press ⌘N (File → New Empty Scene).
2. Move Around the Viewport
- Mouse Controls: Left-click drag to orbit, Right-click or Middle-click drag to pan, and Scroll Wheel to zoom in/out.
- Trackpad Controls: 2-finger scroll to orbit, ⇧ Shift + 2-finger scroll to pan sideways and vertically, and 2-finger pinch gesture to zoom in/out smoothly.
- Fly / Walk Mode (FPS): Press Tab to toggle Fly mode. Drag with Left or Right mouse button (or 2-finger scroll on trackpad) to look around, use WASD to move, E/Space to go up, and Q to go down. Hold ⇧ Shift to fly 3× faster, or scroll / pinch to change your base fly speed.
- Snap to Axis: Click any arm on the 3D Axis Gizmo in the top-right corner of the viewport to snap to Front, Side, or Top views.
- Switch Cameras: Press C (or select from the Camera menu bar) to cycle between the free Viewport Camera and any cameras imported with your scene.
3. Pick Objects & Assign Materials
- Select an Object: Left-click any object in the viewport. It highlights with an outline and loads its material into the Shader Node Editor tab.
- Select a Specific Submesh: Hold ⇧ Shift and Left-click an object to pick the exact material zone/submesh under your cursor.
- Frame Selected Object: Press F or Numpad . to center the camera on your selected object.
- Assign a Material:
In the Shader Node Editor toolbar, pick a material from the dropdown and click Assign to Mesh, or drag the
:: Draghandle next to the material dropdown and drop it directly onto an object in the viewport.
4. Edit Shaders & Load Textures
- Switch to the Shader Node Editor tab (or drag the tab to split your view side by side with the Viewport).
- Add Nodes: Press ⇧ Shift + A, right-click empty canvas space, or drag a wire from any socket and release on empty space to open the searchable Add Node menu.
- Drop in Textures:
Drag any image (
.png,.jpg,.exr,.hdr) from Finder onto the window to create an Image Texture node automatically. - 2D Node Previews:
Click the
Pbutton on the top-right of a node header to toggle a live 2D thumbnail preview right inside the node card. - Cut or Reroute Wires: Hold Ctrl + Right-click drag across a wire to cut it. Hold ⇧ Shift + Right-click drag across a wire to insert a clean reroute dot.
5. Render & Save Images
- Quick Viewport Snapshot: Press F12 at any time to save the current viewport as an 8-bit tonemapped PNG, or ⇧ Shift + F12 to save a 32-bit linear OpenEXR (without the ground grid or selection outline). You can also press ⌘S to pick a custom file name and folder.
- Final Offline Render (F11): Press F11 (or click the Render button in the top-right menu bar) to open the Render Image dialog. Choose your camera, resolution preset (Viewport, 1080p, 1440p, 4K, or Custom up to 8192×8192), Target Samples, and format (PNG or 32-bit EXR), then click Start Render.
Using Blender Live-Link & Sundari Scene Descriptor (.ssd)
What is .ssd?
Sundari Scene Descriptor (.ssd) is Sundari's native directory-based scene format designed for fast geometry loading and sliced updates (so changing a camera or light only re-syncs that tiny slice instead of re-exporting your whole scene).
- In Blender 4.2+, open the 3D Viewport sidebar (N) and select the Sundari tab.
- Set the Package
path (for example,
//my_scene.ssdnext to your.blendfile) and click Start Live Link. Blender will export the initial.ssdpackage and begin watching for changes. - In Sundari, open that
.ssdfolder via ⌘O or drag and drop it onto the Sundari window. You will see a • Live Link indicator appear in Sundari's top menu bar. - Now move objects, adjust lights, or tweak camera focal length, exposure, and depth-of-field in Blender—Sundari updates the path-traced viewport in real time.
- If you add new meshes or change material node trees in Blender, click Export Full Package in the Blender sidebar to push the full update.
What Means What (Settings Reference)
Viewport Top-Right Controls (Render Passes / AOVs)
Use the dropdown in the top-right corner of the Viewport to inspect what the renderer sees under the hood:
| Pass Name | What It Shows & When to Use It |
|---|---|
| Shaded (Beauty) | The full path-traced image with lighting, reflections, and color management. |
| World Normal / Geometry Normal | Surface directions shown as RGB colors. Use this to spot flipped faces, bad smoothing groups, or broken normal/bump maps. |
| Linear Depth | Distance from the camera. Useful for checking scene scale and focus distances. |
| Base Color | Flat surface color without shadows or reflections. Great for checking texture placement and UVs. |
| Roughness | Grayscale view of surface roughness (black = mirror smooth, white = rough matte). |
| Lobe Weights | Color-coded view showing how much diffuse, specular reflection, transmission, and clear coat each surface uses. |
| Grid Checkbox | Shows or hides the reference ground grid plane in the viewport (never included in saved renders). |
Render Settings Tab — Environment Lighting
| Setting | What It Means |
|---|---|
| Mode |
Scene Default:
Uses the lights and environment saved inside your scene file. Environment Map (HDRI): Lights the scene with a 360° HDR/EXR image dome. Lets you load a custom file and rotate the dome. Constant Color: Flat all-around ambient dome lighting. Procedural Sky: Physical sun-and-sky simulator with controls for Sky Model, Sun Elevation (height in the sky), Sun Azimuth (compass direction), and Turbidity (atmospheric haze). |
| Keep Analytical Lights | When overriding the environment with an HDRI or Procedural Sky, check this to keep your scene's point, spot, and area lights turned on too. |
Render Settings Tab — Camera Optics & Frustum
| Setting | What It Means |
|---|---|
| Focal Length & Sensor Size | Controls field of view in millimeters, just like a physical camera lens (default 35mm lens on a 36×24mm full-frame sensor). |
| Focus / f-Stop | Controls Depth of Field (background blur). Dist
sets the exact distance that stays sharp (automatically set when you orbit or frame an object with F). f-Stop
controls blur strength: set to f/0.0
for everything sharp (pinhole), or lower numbers like f/1.4–f/2.8
for shallow cinematic blur. |
Render Settings Tab — Sampling, Light Paths & Clamping
| Setting | What It Means |
|---|---|
| Target Samples (SPP) | How many light samples per pixel to accumulate before stopping. Use 64–256 for quick look-dev, or 1024+ for clean final renders. |
| Light Tree BVH | Smart light sampling for scenes with many lights. Keep this enabled—it drastically reduces noise when your scene has dozens or hundreds of lights. |
| Max Bounces | How many times a light ray can bounce between surfaces. Higher values (8–16) brighten deep indoor corners and complex glass reflections; lower values (2–4) render faster. |
| RR Start Bounce | The bounce count where the renderer starts retiring dim rays early ("Russian Roulette") to save time without darkening the image. Default (3) works well for almost all scenes. |
| Transparent Shadow Steps | How many layers of alpha-cutout or semi-transparent surfaces (like tree leaves or decals) a shadow ray can pass through. |
| Clamp Indirect | Caps super-bright bounced light rays to prevent bright single-pixel specks ("fireflies") from glossy or glass surfaces. Set to 0.0
for unbiased light, or 10.0–20.0
if you see fireflies. |
Render Settings Tab — Color Management
| Setting | What It Means |
|---|---|
| View Transform | How bright scene light is mapped to your screen. ACES and AgX give natural film-like highlight roll-off (AgX preserves color hue in bright lights without clipping to harsh yellow/cyan). Linear shows raw unmapped values. |
| HDR Viewport (EDR) | Allows highlights brighter than standard white to shine on Apple XDR / HDR displays. |
| Exposure (EV) | Brightens or darkens the overall image in camera stops (+1 EV = twice as bright, -1 EV = half as bright). |
OpenPBR Surface Node — Quick Material Guide
Sundari's primary shader node is OpenPBR Surface, organized into collapsible sections so you can build almost any material from one node:
| Section | What It Controls |
|---|---|
| Base | Main surface color, diffuse roughness, and Metalness
(0.0
for plastics/stone/wood, 1.0
for bare metals like gold, copper, or steel). |
| Specular | Surface reflections. Adjust Roughness
(glossy vs. matte), IOR
(index of refraction, default 1.5), and Anisotropy
(brushed metal streaks). |
| Transmission | Clear or frosted glass and liquids. Turn up Weight to make the surface refractive, and use Dispersion to split white light into rainbow caustics like a prism or diamond. |
| Coat | A clear varnish or lacquer layer on top of the base material (great for car paint, wet surfaces, or polished wood). |
| Fuzz | Soft micro-fiber velvet or cloth sheen along grazing edges. |
| Thin Film | Soap-bubble, oil-slick, or iridescent coating interference controlled by film thickness (in nanometers) and IOR. |
| Emission | Makes the surface glow and cast light into the scene (set luminance and emission color). |
| Geometry | Controls Opacity (cutout masks/decals), Thin Walled mode (treat glass as a single sheet like a windowpane instead of a solid block), and normal/bump inputs. |
Keyboard & Mouse Shortcuts
General & Viewport Shortcuts
| Action | Shortcut |
|---|---|
| New Empty Scene | ⌘N |
| Open Scene / Package | ⌘O or Drag & Drop from Finder |
| Open Final Render Dialog | F11 |
| Quick Viewport Snapshot (8-bit PNG) | F12 |
| Quick HDR Viewport Snapshot (32-bit OpenEXR) | ⇧ Shift + F12 |
| Save Viewport Framebuffer As... | ⌘S |
| Open Settings / UI Themes | ⌘, |
| Quit Application | ⌘Q |
| Orbit Camera (Orbit Mode) | LMB Drag (Mouse) / 2-Finger Scroll (Trackpad) |
| Pan Camera (Orbit Mode) | RMB or MMB Drag (Mouse) / ⇧ Shift + 2-Finger Scroll (Trackpad) |
| Zoom In / Out | Scroll Wheel (Mouse) / Pinch Gesture (Trackpad) |
| Toggle Orbit Mode ↔ FPS Fly Mode | Tab |
| Fly Movement (FPS Mode) | WASD + E/Space (Up), Q (Down), ⇧ Shift (Fast) |
| Pick Object / Pick Submesh | LMB Click / ⇧ Shift + LMB Click |
| Frame Selected Object | F or Numpad . |
| Cycle Active Camera (Viewport / Scene Cameras) | C |
| Reset Camera View | R |
Shader Node Editor Shortcuts
| Action | Shortcut |
|---|---|
| Open Add Node Search Menu | ⇧ Shift + A or RMB Click on canvas |
| Pan Node Canvas | MMB or RMB Drag (Mouse) / 2-Finger Scroll (Trackpad) |
| Zoom Node Canvas | Scroll Wheel (Mouse) / Pinch Gesture (Trackpad) |
| Frame All Nodes in View | F or Home |
| Grab / Move Selected Nodes | G or LMB Drag node header |
| Delete Selected Nodes | X, Delete, or Backspace |
| Knife-Cut Node Wires | Ctrl + RMB Drag across wires |
| Insert Reroute Dot on Wire | ⇧ Shift + RMB Drag across wire |
| Move Existing Reroute Dot | ⌥ Option + LMB Drag reroute dot |
Features Not Included in this Release (POC Scope & Limitations)
Proof-of-Concept Boundaries
Sundari v0.1.0 is an early Proof of Concept focused on interactive static-frame look-development, lighting, OpenPBR materials, and real-time spectral light transport on Apple Silicon. The following advanced rendering features are not included in this release:
| Feature | Current Status in v0.1.0 |
|---|---|
| Subsurface Scattering (SSS) | Not included. Translucent organic materials such as skin, marble, wax, jade, and liquids with internal scattering are not yet evaluated via subsurface diffusion or random-walk scattering. |
| Hair & Fur | Not included. Curve and ribbon primitives and dedicated hair BSDFs (Marschner / Chiang models) are not supported. All scene geometry must be polygonal surface meshes. |
| Volumetrics | Not included. Homogeneous or heterogeneous participating media—such as smoke, fire, atmospheric haze, cloud density volumes, or volumetric absorption/scattering—are not supported. |
| Animation & Timeline | Not included. Skeletal animation rigs, vertex deformation playback, Alembic point cache streaming, and multi-frame animation sequence rendering are not supported. Sundari v0.1.0 is built for interactive static-frame look-dev and real-time camera framing. |
| Motion Blur | Not included. Neither camera shutter motion blur nor linear/curved transform or geometry deformation motion blur is evaluated in this static look-dev release. |
| Dynamic Subdivision & Displacement | Not included. Geometry must be pre-subdivided and pre-triangulated before import; run-time micro-polygon displacement and dynamic Catmull-Clark subdivision are not supported. |
Recommended Sample Scenes & Test Assets
Sample scenes are not bundled into the binary download. Instead, you can download these industry-standard production stages, material libraries, and benchmark scenes to test directly in Sundari:
ASWF MaterialX Teapot & Lion
The official look-development benchmark asset from the Academy Software Foundation (ASWF) and the Digital Production Example Library (DPEL). Features intricate production geometry, multi-lobe OpenPBR surface shaders, and studio look-dev turntable lighting.
NVIDIA Omniverse Industrial Asset Pack
Large-scale industrial warehouse environment packed with modular shelving, machinery, heavy equipment, and instanced architectural elements. Ideal for testing OpenUSD stage hierarchy loading and complex scene ray tracing.
ASWF MaterialX Official Examples
The Academy Software Foundation's comprehensive suite of MaterialX test documents, shader graphs, procedural patterns, and surface definitions. Includes standard surface materials, car paints, metals, coated plastics, and glass looks ready to drop into Sundari.
Blender Classroom Benchmark Scene
The renowned Blender Foundation interior architectural benchmark scene with complex geometric detail, window daylighting, and layered classroom props. Test it with Sundari via the Blender Live-Link add-on or export it to .ssd.
Feedback, Bug Reports & Contact
Sundari is in active Proof-of-Concept testing. If you encounter bugs, crashes, or rendering artifacts, or if you want to reach out:
- File a Bug Report: Open an issue on GitHub at github.com/SundariRenderer/sundari-issues. Please include your Mac model, macOS version, and steps to reproduce.
- Email & Direct Contact: You can also email bug reports, feedback, or general questions directly to urjasvisuthar@zohomail.in.