Getting Started

Getting Started with OxyBrush

This guide covers installing OxyBrush, your first launch, navigating the user interface, and sculpting your first 3D model.

---

System Requirements

OxyBrush is built on wgpu and uses modern graphic APIs for performance:

Component	Minimum Requirements	Recommended Specifications
Operating System	Windows 10/11 (64-bit), macOS 12+ (Apple Silicon or Intel), Linux (glibc 2.31+)	Windows 11, macOS 14+, modern Linux distribution
Graphics API	DirectX 12, Vulkan 1.2+, or Metal 2.0+	Modern dedicated GPU with full Vulkan/Metal support
System Memory (RAM)	8 GB	16 GB - 32 GB for multi-million polygon meshes
Input Devices	Mouse & Keyboard	Pressure-sensitive Pen Tablet (Wacom, Huion, XP-Pen, Apple Pencil via Sidecar)

---

Installation

Download the official binaries for your platform from the GitHub Releases page.

Windows

• Installer (.exe / .msi): Run the installer wizard to set up start menu shortcuts and file associations.
• Portable Zip (.zip): Extract anywhere and run oxybrush.exe. No admin privileges required.

macOS

• Download OxyBrush-vX.Y.Z-macos.dmg.
• Double-click the DMG and drag OxyBrush into your Applications folder.
• Apple Silicon & Intel: OxyBrush universal binaries run natively on both M-series and Intel Macs.

Linux

• Flatpak (.flatpak):

  flatpak install OxyBrush.flatpak
  flatpak run com.crisprintsstuff.OxyBrush

• Portable Tarball (.tar.gz):

  tar -xzf oxybrush-v*-x86_64-unknown-linux-gnu.tar.gz
  cd oxybrush
  ./oxybrush

Building From Source

If you have the Rust toolchain installed (rustc and cargo 1.80+):

git clone https://github.com/crisprintsstuff/OxyBrush.git
cd OxyBrush
cargo run --release -p oxy-app

---

First Launch & Welcome Screen

When you first launch OxyBrush, a welcome dialog gives you quick access to recent projects, starter templates, and layout presets:

1. Starter Templates:
   • Default Sphere: A clean subdivision quad-sphere ideal for character heads and organic sculpts.
   • Dynamesh Blockout: A voxelized primitive ready for immediate high-amplitude deformation.
   • Plane: A tessellated flat grid for terrain, relief carving, and texture alpha sculpting.
   • Empty Scene: Start blank or immediately import OBJ, glTF, or STL meshes.
2. Interface Layout Modes:
   • Standard Layout: Full dual-side panels with tool settings, layers, outliner, and history.
   • Compact Layout: Collapsible side drawers for small laptop screens.
   • Touch / Tablet Mode: Enlarged UI hit-targets and on-screen gesture modifiers for pen displays and tablets.

---

User Interface Tour

+-----------------------------------------------------------------------------------+
|  [Menu Bar: File | Edit | Mesh | Tools | Plugins | Help]                          |
+----+-------------------------------------------------------------------------+----+
| B  |                                                                         | B  |
| R  |                                                                         | R  |
| U  |                         3D VIEWPORT CANVAS                              | U  |
| S  |                                                                         | S  |
| H  |  - Click & drag to sculpt                                               | H  |
| E  |  - Right-drag / Alt-drag to orbit camera                                |    |
| S  |  - Interactive On-Canvas Brush Ring                                     | P  |
|    |                                                                         | R  |
| T  |                                                                         | O  |
| O  |                                                                         | P  |
| O  |                                                                         | E  |
| L  |                                                                         | R  |
| B  |                                                                         | T  |
| A  |                                                                         | I  |
| R  |                                                                         | E  |
|    |                                                                         | S  |
+----+-------------------------------------------------------------------------+----+
|  [Status Bar: Vertices: 131,074 | Triangles: 262,144 | FPS: 60 | Multires: Level 3] |
+-----------------------------------------------------------------------------------+

• Top Bar: Quick project controls, undo/redo, symmetry toggle (X), remesh triggers, and subdivided level switchers.
• Left Toolbar: Quick selection of all 16 sculpting brushes (1 through 9, 0, and shortcut hotkeys).
• Viewport Canvas: Real-time 3D interactive viewport rendering matcaps, cavity shading, and wireframes.
• Right Panel Tabs:
  • Brush Settings: Radius, strength, falloff curves, stroke stabilization, and alpha textures.
  • Mesh / Multires: Subdivision levels, voxel remeshing resolution, quadric decimation sliders.
  • Materials & Display: Matcap presets, ambient occlusion, cavity depth, wireframe overlays.
  • Outliner & Pieces: Multi-mesh hierarchy and visibility toggles.
  • History: Undo/redo stack inspection.

---

Your First Sculpt: Step-by-Step

Let's sculpt a quick stylized character head in 5 simple steps:

1. Start with the Default Sphere: Launch OxyBrush and choose Default Sphere.
2. Enable Symmetry: Press X on your keyboard (or toggle the Symmetry icon in the top toolbar). Changes made on the left side will mirror across the X-axis.
3. Rough Out the Silhouette (Grab Brush):
   • Press G to select the Grab Brush.
   • Press [ or ] (or hold F and drag) to enlarge the brush radius.
   • Pull the bottom of the sphere downward to form the jaw and chin.
   • Push the sides inward slightly to define the temples.
4. Build Facial Planes (Clay Strips Brush):
   • Press C to switch to Clay Strips.
   • Lay down parallel strokes for the brow ridge, nose bridge, and cheekbones.
   • Hold Alt while stroking to carve inward for eye sockets.
5. Smooth and Refine:
   • Hold Shift at any time to temporarily engage the Smooth Brush. Lightly blend harsh intersections.
   • Press D to step up one subdivision level (or press Ctrl+D to subdivide if at maximum level).
   • Use the Crease Brush (Shift+C) to sharpen eyelids and the mouth line.
6. Save Your Work: Press Ctrl+S to save your work as an OxyBrush project file (.oxy), or go to File > Export to export an OBJ or STL for 3D printing.