3D Car Viewer and Ad Preview
Relevant source files
The following files were used as context for generating this wiki page:
The 3D Car Viewer and Ad Preview system provides an interactive, real-time visualization of a Mini Cooper S 2021 model equipped with dynamic advertising placements. This component serves as the primary interface for users to browse available ad spots, view current sponsor artwork, and preview their own designs before committing to a bid. It integrates high-fidelity 3D rendering with a live auction backend to ensure the displayed livery remains current.
The system utilizes Three.js for client-side rendering and supports Draco mesh compression for efficient model delivery. Users can rotate, zoom, and focus on specific car surfaces, each mapping to a unique slot_id in the auction database.
Sources: apps/website/src/components/car-viewer.tsx, apps/website/README.md:143-157, apps/mini-livery/README.md:5-15
Component Architecture
The 3D viewer is built as a React component (CarViewer) that encapsulates a Three.js rendering pipeline. It manages a Runtime state containing the scene, camera, renderer, and asset caches.
Rendering Engine and Assets
The viewer loads a GLB model derived from CARLA 0.9.16 vehicle geometry. It uses GLTFLoader with DRACOLoader for mesh decompression. The environment is lit using a RoomEnvironment for metallic paint reflections and a DirectionalLight to cast shadows on a plane beneath the car.
Sources: apps/website/src/components/car-viewer.tsx:88-100, apps/website/src/components/car-viewer.tsx:165-185, apps/mini-livery/README.md:32-37
Logic and Data Flow
The system synchronizes the 3D scene with the live auction state provided via WebSockets. When the placements prop updates, the component dynamically generates or updates materials for specific meshes identified as "logo surfaces".
This diagram illustrates how live auction updates trigger texture refreshes in the 3D environment.
Sources: apps/website/src/components/car-viewer.tsx:327-360, apps/website/README.md:154-157
Interactive Features
The viewer provides several methods for interaction and navigation:
Camera Controls and Views
The system defines preset angles for different vehicle faces. The camera uses OrbitControls with damping and constraints to prevent the user from looking beneath the floor.
| View ID | Purpose | Description |
|---|---|---|
perspective | Overview | The default opening view showing the car at an angle. |
left / right | Side View | Focused view of the doors and side windows. |
top | Roof View | Overhead view of the bonnet and roof. |
front / back | End Views | Focused view of the grille and rear window. |
Sources: apps/website/src/components/car-viewer.tsx:55-62, apps/website/src/components/auction-site.tsx:28-35
Selection and Raycasting
The component uses THREE.Raycaster to detect pointer interactions. It traverses the hit object's hierarchy to find a slot_id in userData. When a slot is selected, the camera automatically frames the targeted panel using predefined faceDirections.
Sources: apps/website/src/components/car-viewer.tsx:238-260, apps/website/src/components/car-viewer.tsx:112-132
Ad Placement and Livery Logic
Each advertising space is a specific mesh within the GLB model with the role logo_surface.
Mesh Projection and UV Mapping
The rebuild-layout.py script reprojects panels onto the car body based on a layout.json specification. It generates a 0-1 UV layout for each panel, ensuring that sponsor artwork is fitted without stretching.
- Logo Surfaces: Mesh targets for advertiser artwork.
- Availability Markers: Dashed borders and "YOUR LOGO HERE" text that are hidden when a spot is occupied.
- Emissive Highlighting: Selected or hovered spots glow using an emissive material property.
Sources: apps/mini-livery/rebuild-layout.py:65-95, apps/website/src/components/car-viewer.tsx:430-450, apps/mini-livery/README.md:20-25
Texture Application
The viewer applies advertiser artwork by creating a MeshStandardMaterial with the logo texture. If the artwork's aspect ratio differs from the panel, the system crops and scales the image to fit a 1024x1024 canvas before creating a CanvasTexture.
Sequence of events for loading and applying new sponsor artwork to the 3D car.
Sources: apps/website/src/components/car-viewer.tsx:365-410, apps/website/README.md:143-150
Asset Validation and Exports
The 3D viewer relies on a frozen model generated by the rebuild-layout.py script.
- Model Compression: The web derivative uses 2K paint textures and Draco mesh compression for fast loading.
- Livery Export: The
export:liveryscript generates a frozen snapshot of the current livery for use in external rendering engines (like native CARLA or Blender). This export includes transparent PNGs fitted to panels and amanifest.jsonmapping sponsors to meshes.
Sources: apps/website/LIVERY-EXPORT.md:5-15, apps/mini-livery/README.md:46-52, apps/mini-livery/rebuild-layout.py:155-165
Summary
The 3D Car Viewer and Ad Preview module bridges the gap between the live auction data and a high-fidelity visual representation. By utilizing projected meshes and dynamic texture loading, it provides an accurate preview of how advertising artwork will appear on the physical bodywork of the simulated Mini Cooper S.