Installation & Getting Started

Welcome to the Models3D Studio for WooCommerce Knowledge Base!

This plugin empowers your WooCommerce store with a high-performance, interactive 3D model viewer via React Three Fiber (R3F), allowing customers to inspect products from every angle before purchasing.

Installation

1. Download the models3d-studio.zip file from your purchase dashboard.
2. In your WordPress admin panel, navigate to Plugins -> Add New.
3. Click Upload Plugin at the top of the page.
4. Select the .zip file and click Install Now.
5. Once installed, click Activate Plugin.

Adding a 3D Model to a Product (BYOM)

1. Navigate to Products -> All Products in your WordPress admin.
2. Edit an existing product or click Add New.
3. In the core Product data box, click the dedicated 3D Studio tab.
4. Choose your 3D asset source:
   • Local File: Drag and drop your .glb or .gltf file directly into the upload zone.
   • Remote URL: Paste an external HTTPS URL to load models directly from a CDN or media bucket.
   • Starter Library: Pick one of the bundled starter models (High-Performance Sports Car, Athletic Sneaker, or Designer Sunglasses) for immediate zero-friction testing.
5. The plugin automatically executes Pre-Flight validation to verify vertex counts (<250,000) and structural integrity.
6. Click Update or Publish to save the product.
7. Your frontend product gallery will now feature a high-performance 3D canvas instead of (or alongside) traditional images.

TIP

Resilient REST Media Uploads (v1.1.3): Models3D Studio includes built-in session auto-healing for WordPress REST uploads. If duplicate or path-shadowed browser cookies are present, the plugin automatically repairs the authentication token, preventing false "Cookie check failed" 403 errors.

Supported Formats

• .GLB (Recommended): The binary form of glTF. It bundles all textures, shaders, and geometry into a single, highly compressed file.
• .GLTF: The JSON form of glTF. Ensure all associated .bin and texture files are uploaded together.

The WooCommerce Product Data Tab

When editing any WooCommerce product (Simple or Variable), you will find a dedicated 3D Studio tab located directly inside the core Product data meta box alongside Inventory, Shipping, and Attributes.

Features in the 3D Studio Tab

• Upload or Import: Drag and drop a custom model (.glb / .gltf) or paste a remote URL for seamless self-contained loading.
• Bundled Starter Model Selector: Quickly load one of the built-in 3D assets to test the studio environment without external files.
• Launch Visual Editor: A prominent button that launches the full-screen visual configuration workspace.
• Toggle Developer JSON View: Advanced users can reveal the raw JSON configuration array stored in WordPress post-meta. You can manually inspect, copy, or bulk-edit this JSON directly from the product edit screen.

Global Plugin Settings Dashboard

Models3D Studio features a dedicated global settings control center under WooCommerce -> 3D Studio -> Settings (admin.php?page=models3d-studio&tab=settings). This console enables store administrators to configure site-wide canvas placement, viewport dimensions, and theme compatibility behaviors.

Canvas Placement Strategies (models3d_canvas_placement)

Control how the interactive 3D WebGL canvas attaches to single product pages:

• Replace Gallery (replace - Default): Completely replaces WooCommerce's default product image gallery hook (woocommerce_show_product_images). Designed for stores providing an immersive, 3D-first product showcase in place of static photography.
• Append to Gallery (append): Hooks into woocommerce_product_thumbnails to render the 3D canvas directly below the standard product image gallery. Visitors can explore standard photo galleries and 3D models side-by-side.
• Manual Shortcode Only (shortcode): Suppresses automated theme template interception entirely. Allows you to manually position the 3D viewer anywhere on the page using the [models3d_viewer] shortcode or inside custom page builder templates.

Viewport Dimension Calibration

Ensure clean visual presentation across all device viewports:

• Desktop Canvas Height (models3d_canvas_height_desktop): Sets the CSS viewport height on desktop screens (defaults to 600px). Accepts valid CSS units (px, vh, rem, em, %).
• Mobile Canvas Height (models3d_canvas_height_mobile): Sets the CSS height on mobile viewports under 768px (defaults to 400px). Prevents oversized canvases on smaller mobile screens. Accepts valid CSS units (px, vh, rem, em, %).

Strict Compatibility Mode (models3d_strict_compatibility_mode)

When enabled (yes), EventBridge activates strict defensive DOM querying and polling timeouts. This guarantees seamless variation synchronization on stores using heavily customized child themes, AJAX page transitions, or non-standard variation swatch plugins that override standard WooCommerce form events.

Frontend Shortcode & Page Builder Integration

For stores designed with visual page builders (Elementor, Divi, Bricks, Gutenberg) or custom templates, Models3D Studio provides a high-performance frontend shortcode:

[models3d_viewer id="476" class="custom-showcase-viewer"]

Shortcode Parameters

• id (optional): The WooCommerce Product ID to render. If omitted on a single product page, the shortcode automatically resolves and displays the current product's 3D asset.
• class (optional): Additional CSS classes appended to the wrapper element (.models3d-shortcode-wrapper.custom-react-gallery-wrapper) for custom styling or responsive containment.

Architectural Collision Guard

To prevent duplicate WebGL contexts, redundant EventBridge bindings, and GPU memory leaks, the shortcode engine includes an Architectural Collision Guard (GalleryArchitect.php#L82):

• When the global placement setting is set to Replace Gallery (replace) and the [models3d_viewer] shortcode is embedded on that same product's single product page (e.g. inside product description tabs), the shortcode automatically self-suppresses.
• Because the primary gallery hook already mounts the 3D canvas for that product, suppressing duplicate mounts ensures single WebGL instance integrity and maintains 60 FPS performance.

Page Builder Decoupled Enqueuing

Page builders like Elementor, Divi, and Bricks frequently store layout structures in custom metadata rather than standard post content. Models3D Studio uses decoupled late-asset enqueuing (GalleryArchitect.php#L88) to guarantee that React Three Fiber scripts, Draco WASM decoders, and canvas styles load reliably across all page builder environments.

Starter 3D Model Library

To facilitate rapid prototyping and testing without requiring external 3D assets, Models3D Studio includes a bundled library of production-grade 3D assets:

• High-Performance Sports Car: High-fidelity automotive model featuring distinct mesh layers for body paint, carbon fiber aero trim, tinted windows, wheels, brake calipers, and cockpit interior.
• Athletic Running Sneaker: Complex footwear geometry with separate mesh nodes for rubber sole, knit upper, fabric tongue, laces, eyelets, and accent stripes.
• Designer Sunglasses: Modern eyewear asset with acetate frames, polarized UV lenses, metallic temple hinges, and nose pads.

Instant 1-Click Loading

You can load any starter model with a single click from the 3D Studio product tab or directly inside the 3D Model workspace of the Visual Editor. The asset's complete mesh hierarchy is immediately extracted, enabling instant attribute and material mapping.

Step-by-Step Tutorial: Building a 3D Configurable Product

Follow this comprehensive, hands-on tutorial to learn how to create a variable WooCommerce product, attach a high-performance 3D model, calibrate lighting and camera angles, configure colorways and modular parts, and verify live dynamic switching on your storefront.

Full Video Walkthrough

Watch the complete 11-minute hands-on video walkthrough covering every click from initial WooCommerce variable product setup to 3D GLB model upload, PBR material tuning, modular mesh visibility overrides, and live storefront testing:

Video Chapters & Timestamps

• 00:00 — Creating a Variable Product & Setting Featured Image
• 00:21 — Configuring Attributes: color, lace, sole, size
• 01:37 — Generating 48 Product Variations & Setting Bulk Regular Price
• 02:06 — Attaching the 3D GLB Model in the 3D Studio Tab
• 02:25 — Publishing Product & Launching the Visual Studio Editor
• 02:33 — Visual Editor Workspace Overview (Dual-Channel Architecture)
• 03:01 — Scene Lighting Presets, Background Gradients [PRO] & Contact Shadows
• 03:25 — Turntable Auto-Rotation, 3D Model Rotation Speed Control [PRO] & Camera FOV Calibration (31°)
• 03:45 — Capturing the Default 3/4 Hero Camera View
• 04:01 — Material & Finish: Mapping PBR Colors to Shoe Upper Mesh
• 06:16 — Mesh Layers Visibility Toggles [PRO]: Modular Laces with 🎯 Pick 3D
• 07:26 — Mesh Layers Visibility Toggles [PRO]: Modular Outsoles with 🎯 Pick 3D
• 08:46 — Saving Configuration & Live Status Confirmation
• 09:01 — Live Storefront Demo: Instant 3D Color & Geometry Swapping
• 09:46 — Visual Editor Layer Sync & Lighting Touch-ups
• 10:47 — Final Storefront Showcase: Interactive 360° Orbit & Swatches

---

Phase 1: WooCommerce Variable Product & Attributes

Before opening 3D Studio, always define your product attributes and variations natively in WooCommerce. This ensures all variation options are stored in the database and automatically populated inside the 3D Visual Editor.

1. In WordPress Admin, navigate to Products -> Add New.
2. Enter the product title (e.g. "sneaker").
3. In the Product data dropdown, select Variable product.
4. Click the Attributes tab and add four custom attributes:
   • color: red | white | blue (Check Used for variations).
   • lace: Option A | Option B (Check Used for variations).
   • sole: Option A | Option B (Check Used for variations).
   • size: L | XL | XXL | XXXL (Check Used for variations).
5. Click Save attributes.
6. Switch to the Variations tab and click Generate variations (or Regenerate variations). WooCommerce will create all 48 combinations ($3 \times 2 \times 2 \times 4 = 48$).
7. Under Bulk actions, select Set regular prices, enter 200.00, and click OK.
8. Set the main product image in the sidebar Product image box.

---

Phase 2: Attaching the 3D Model

With variations saved, attach your 3D asset directly inside the product edit screen:

1. Click the dedicated 3D Studio tab in the Product data box.
2. Under the Sample Model library, click Load Model on the Athletic Sneaker Showcase (0.61 MB, 10 layers), or drag-and-drop your custom .glb asset into the upload zone.
3. The Pre-Flight Inspector verifies vertex counts and topology.
4. Click Publish (or Update) in the top-right WordPress Publish box to save the post-meta.

---

Phase 3: Scene Lighting, Turntable & Merchandising Camera View

Launch the fullscreen Visual Editor to establish the environment lighting and default camera perspective:

1. Click Launch Visual Editor from the 3D Studio product tab.
2. In the top navigation, click the Scene & Lights workspace:
   • Lighting Preset: Select from 10 built-in Drei studio presets (e.g. Warehouse, Studio, Sunset, City) for balanced specular highlights. (Note: Custom .HDR studio lighting & brand reflections are exclusive to Models3D Studio Pro).
   • Light Intensity: Adjust slider from 0.1x to 3.0x (recommended: 1.2x – 1.5x) for vibrant reflections without clipping.
   • Canvas Background: Set to Transparent to blend with your WooCommerce theme, or pick a custom solid color. (Note: Background gradients & image backdrops are unlocked in Models3D Studio Pro).
   • Ground Shadows: In v1.1.3, Enable Ground Shadows is set to OFF by default to maximize 60fps rendering speed. Toggle ON if you desire ambient occlusion contact shadows beneath the product.
   • Turntable Auto-Rotate & Rotation Speed: Toggle ON for continuous 360° showcase rotation. In the Free Community Edition, turntable auto-rotation runs at a standard fixed 1.0x velocity. Upgrading to Models3D Studio Pro unlocks the 3D model rotation speed control from 0.1x to 10.0x, enabling slow-motion luxury spins or high-energy dynamic rotations.
3. Under Camera & Default Framing:
   • Field of View (FOV): Dial down to 10°–20°. Narrowing the FOV creates an orthographic/telephoto appearance that eliminates wide-angle distortion.
   • Orbit the product in the canvas to your preferred 3/4 hero angle.
   • Click Capture Current View as Default. This locks the coordinates as is_custom: true, guaranteeing that every store visitor lands on this exact perspective.

---

Phase 4: Material Swaps & PBR Finishes

Switch to the Materials workspace. Notice that Models3D Studio automatically extracts your WooCommerce attributes (e.g., color (3), lace (2), sole (2), size (4)):

1. Configuring Option: red

• Under color, select the red pill.
• In the sidebar, expand the Material & Finish accordion.
• Choose a color preset or dial in Base Color to #d62828, then adjust Roughness and Metalness sliders.
• Under Target Mesh Layers, use the layer search bar or click directly on the 3D canvas to select target meshes (e.g., Shoe Upper Mesh).
• The 3D canvas updates immediately with the vibrant red coating.

2. Configuring Option: white

• Select the white pill under color.
• In Material & Finish, set Base Color to #ffffff (crisp white) or toggle Keep Original Model Material if your 3D model already has baked base textures.
• Target the same Shoe Upper Mesh layer.

3. Configuring Option: blue

• Select the blue pill under color.
• In Material & Finish, set Base Color to #2196f3 (electric blue) with subtle gloss.
• Target Shoe Upper Mesh. The 3D model instantly morphs to dynamic blue.

---

Phase 5: Modular Geometry Swapping with Visibility Overrides

PRO CAPABILITY: MESH LAYERS VISIBILITY TOGGLES

Mesh layers visibility toggles (Channel 2) and the 🎯 Pick 3D in-viewport tool are exclusive capabilities of Models3D Studio Pro.

In the Free Community Edition, variation cards feature Channel 1 (Material & Finish) while Channel 2 displays an interactive preview teaser card. Upgrading to Models3D Studio Pro activates full dual-channel configurators with dynamic Show/Hide rules for swapping physical geometries.

When variations require swapping physical parts—such as modular lace styles or outsole geometries—use the Visibility channel:

1. Attribute: lace (Modular Laces)

• Click the lace (2) attribute tab.
• Expand the Visibility accordion.
• For Option A: Use 🎯 Pick 3D to click the sport laces directly on the model (or search the layer list) and set Shoe Laces Classic to visible and Shoe Laces Sport to hidden.
• For Option B: Invert the visibility rules—set Shoe Laces Sport to visible and hide Shoe Laces Classic.

2. Attribute: sole (Interchangeable Outsoles)

• Click the sole (2) attribute tab.
• Expand the Visibility accordion.
• For Option A: Bind to Shoe Sole Classic (Show) and hide Shoe Sole Platform.
• For Option B: Use 🎯 Pick 3D on the platform sole to show Shoe Sole Platform and hide Shoe Sole Classic.
• The 3D viewport instantly switches the physical outsole geometry when toggling between options.

---

Phase 6: Storefront Verification & Cart Integration

Save your changes and preview the live WooCommerce product page:

1. In the top-right header of the Visual Editor, click Save Changes. A confirmation toast will confirm that the configuration was saved to WordPress post-meta.
2. Click Exit Editor and view the product on your live storefront (/product/sneakers/ or /product/sn/).
3. Verify Interactive Morphing:
   • Change Color in the dropdown or swatch (RED, Blue, White):
     • Selecting RED renders the deep metallic red finish.
     • Selecting Blue morphs the body to vibrant high-gloss blue in real time.
     • Selecting White switches to crisp pearl white.
   • Notice that material transitions occur instantly with zero page reloads via the built-in R3F EventBridge.

4. Click Add to cart.
5. Navigate to the Cart page: verify that the line item displays the exact selected variation string (e.g. Color: Blue / Lens: Option A / Sole: Option A) at the configured regular price.

---

Frequently Asked Questions

A curated list of common inquiries regarding Models3D Studio, performance guidelines, and WooCommerce integration.

General Setup

Do I need prior 3D modeling experience?

No. Models3D Studio operates on a Bring-Your-Own-Model (BYOM) architecture. Assuming you have a standard .glb or .gltf file, our Visual Editor allows you to intuitively map variations and adjust camera angles without touching a single line of 3D code.

Does it work seamlessly with variable products?

Yes. You must first create and save your attributes natively in WooCommerce. Once saved, you can launch the Visual Editor, click directly on any mesh layer in the 3D viewport, and link it to your existing attribute options.

Can I duplicate mesh selections across all options?

Yes. Click the Sync to All Options button in the variation card footer. The plugin will automatically replicate the current mesh layer assignments across all other terms of that attribute in a single click.

Performance & Sizing

How does the plugin handle models of drastically different physical sizes?

Models3D Studio features a Scale-Aware 3D Auto-Framing Engine. On model load, the engine calculates the asset's true geometric bounding sphere and dynamically sets the camera distance, frustum near/far clipping planes, and orbit zoom limits. A 20cm sneaker and a 5m sports car are both framed at their optically ideal distance automatically.

Why is my model failing to upload?

Models3D Studio enforces a strict 250,000 vertex ceiling. This is an absolute limit designed to guarantee a 60fps rendering experience, prevent memory leaks, and stop excessive mobile battery drain. If your file exceeds this limit, the pre-flight validator will intercept it. You must decimate your geometry in Blender or utilize our built-in WASM Optimizer.

Does the plugin handle texture compression?

Yes. The plugin integrates native Draco compression via WebAssembly (WASM). During the optimization phase, textures and geometry can be heavily compressed for the web, drastically reducing load times without sacrificing visual fidelity.

Technical Troubleshooting

Why is my model completely black or missing textures?

This is almost universally a CORS (Cross-Origin Resource Sharing) configuration issue. If your store uses a CDN (like Cloudflare) or offloads media to a separate subdomain, WebGL cannot securely load the textures unless the correct Access-Control-Allow-Origin headers are present.

Why do I see a "Cookie check failed" error when uploading models?

In WordPress, browser cookie shadowing across root paths or stale duplicate session cookies can occasionally cause REST API authentication checks to reject valid uploads with a 403 error. Starting in v1.1.3, Models3D Studio automatically intercepts and heals duplicate session cookies via determine_current_user, isolating the valid authentication token so that model uploads succeed seamlessly without requiring manual cookie clearance.

How do I test Pro features on staging or local environments?

Local and staging license testing is handled natively through Freemius Cloud under WooCommerce -> 3D Studio -> License. You can activate developer sandbox keys or staging licenses directly in the Freemius management interface without configuring custom server constants.

Can I install and activate the Pro version while the Free edition is currently active?

Yes. Starting in v1.1.3, Models3D Studio features an automatic sibling deactivation guard. When you upload and activate models3d-studio-pro.zip, WordPress cleanly deactivates the Free community edition without triggering PHP class redeclaration fatal errors. All your existing 3D assets, camera presets, and variation rules are preserved untouched.

What happens to my 3D configurations during plugin uninstallation?

By default, uninstallation preserves all product 3D configurations in WordPress post-meta to prevent accidental data loss during updates. If you wish to purge all plugin data completely upon deletion, enable the Erase all 3D Studio data on uninstallation toggle in plugin settings.

Creative Studio: Overview & Workspaces

The core of Models3D Studio is the Creative Studio Visual Editor. Re-architected for 2026, the editor splits 3D product customization into three specialized workspaces for optimal productivity:

The Three Workspaces

1. 🎨 Materials Workspace: Focused on WooCommerce attribute binding, 1-click PBR material presets, smart mesh group accordions, color pickers, roughness/metalness sliders, and variation-specific camera views.
2. 💡 Scene & Lights Workspace: Focused on environment HDRI lighting presets (with Pro custom .HDR lighting & brand reflections), exposure intensity, ground contact shadows, turntable auto-rotation speed tuning, and background styling (transparent, solid color, and Pro background gradients & image backdrops).
3. 📦 3D Model Workspace: Focused on 3D asset inspection, vertex counts, wireframe topology display, and the bundled starter 3D model library.

Launching the Editor

You can launch the visual editor for any simple or variable WooCommerce product:

1. Navigate to Products -> All Products and edit your product.
2. In the Product data meta box, click the 3D Studio tab.
3. Ensure a 3D model is uploaded or select a starter model.
4. Click the prominent Launch Visual Editor button.

Materials Workspace & PBR Presets

The Materials Workspace provides deep, real-time control over the visual appearance of your 3D assets mapped to WooCommerce variation options.

1-Click PBR Material Presets Bar

Apply photorealistic physical materials to selected meshes with a single click:

• Car Paint: Deep, high-gloss automotive finish with fine-tuned micro-roughness and high specular reflection.
• Carbon Fiber: High-tech woven graphite composite with structured matte-gloss contrast.
• Chrome: Ultra-reflective mirror finish (100% metalness with minimal roughness).
• Tinted Glass: Sleek semi-translucent aesthetic with controlled surface smoothness.
• Matte Rubber: Low-reflectivity matte finish engineered for footwear soles, grips, and tires.
• Polished Gold: Premium warm metallic sheen with calibrated reflectivity.
• Matte Plastic: Contemporary non-reflective polymer aesthetic suitable for modern electronics and accessories.

Keep Original Model Material Toggle

When toggled on, custom color and roughness overrides are deactivated, preserving the original textures, vertex colors, and shaders baked into the GLTF file by the 3D artist. Activating this toggle automatically deselects active preset pills.

Single vs. Multi Mesh Selection Mode

At the top right of each variation card, you can toggle between two selection modes:

• Single Mode: Targets exactly one mesh layer per rule for pinpoint component adjustments.
• Multi Mode: Select multiple mesh layers simultaneously. Any color, roughness, metalness, or visibility change applies to all selected meshes at once.

Smart Mesh Categories & Accordions

The editor automatically analyzes mesh names and groups them into logical functional categories (e.g. Body, Wheels, Interior, Accents, Sole, Upper, Frame, Lenses):

• Collision Guards: Keyword matching utilizes word boundaries (e.g. \btrim\b vs \brim\b) to prevent incorrect categorization.
• Smart Expansion: Accordion categories containing active mesh selections automatically expand, while inactive groups stay collapsed to reduce cognitive load.
• Quick Expand: Clicking [All] inside any category header immediately expands the accordion and selects all child mesh layers.

1-Click "Sync to All Options"

Located in the variation card footer, the Sync to All Options button duplicates the currently selected mesh layers across every variation term in that attribute. This eliminates repetitive manual selections when configuring multi-color product lines.

Attribute & Option Navigation

Navigating complex products with dozens of variation terms is effortless thanks to dedicated horizontal tab navigation with physics-based interactions:

• "Product Attributes" Eyebrow Header: Provides a clear visual hierarchy distinguishing WooCommerce product attributes from variation options.
• Frictionless Grab-to-Scroll: Drag horizontally with mouse or touch to pan smoothly across extensive lists of attributes and option pills.
• Misclick Suppression: A built-in drag threshold prevents accidental clicks when panning through options.
• Ultra-Smooth Auto-Centering: Clicking an option tab glides it to the center of the viewport over 420ms using easeOutQuint deceleration physics. DOM-preserving active class updates eliminate disruptive re-renders.
• Custom 4px Minimalist Scrollbars: Sleek, low-profile scrollbars appear when attribute tabs overflow, ensuring clear visual affordance across desktop browsers.

Scene & Lights Workspace

The Scene & Lights Workspace controls the environmental ambiance, lighting, and background framing of the 3D canvas:

HDRI Environment Presets

Choose from 10 high-dynamic-range lighting environments built on @react-three/drei:

• Studio: Clean, neutral product photography lighting with balanced rim lights.
• Warehouse: Crisp industrial lighting with bright specular reflections.
• Warm Sunset: Golden-hour natural illumination with warm highlights.
• Dawn: Soft morning ambient glow.
• Forest: Natural outdoor ambient lighting with soft green and earth tones.
• Apartment: Cozy interior ambient illumination with domestic light bounces.
• Park: Vibrant open-air daylight.
• Lobby: Architectural indoor lighting with polished floor reflections.
• Urban City: Crisp outdoor daylight with architectural reflection maps.
• Night Studio: Moody, dramatic low-key contrast lighting.

PRO FEATURE: CUSTOM .HDR STUDIO LIGHTING & BRAND REFLECTIONS

While the Free Community Edition includes these 10 Drei studio presets, merchants upgrading to Models3D Studio Pro can upload proprietary equirectangular .hdr files directly to the WordPress Media Library. This unlocks branded showroom reflections, independent 360° environment spinning, and dynamic studio lux exposure calibration.

Environment Lighting Intensity

A fine-grained numeric slider (0.1x to 3.0x) with live percentage readout allows precision tuning of scene brightness without blowing out specular highlights.

Ground Contact Shadows

Toggle soft ambient occlusion contact shadows beneath the model. Shadows ground the product in 3D space and are mathematically isolated from bounding-box centering calculations to ensure accurate model auto-framing.

NOTE

Performance Default in v1.1.3: Ground Contact Shadows are set to OFF (shadows_enabled: false) by default. This guarantees immediate sub-second initial canvas rendering and 60 FPS mobile performance out of the box, while allowing merchants to toggle them on with a single click.

Turntable Auto-Rotate & 3D Model Rotation Speed Control

• Continuous 360° Presentation (Free & Pro): Toggle Auto-Rotate 3D Model to smoothly spin the model around the vertical axis for an automatic storefront showcase.
• The 3D Model Rotation Speed Control (PRO ONLY): In the Free Community Edition, turntable auto-rotation spins at a standard fixed 1.0x velocity. Upgrading to Models3D Studio Pro unlocks fine-tuned rotation speed calibration from 0.1x to 10.0x, allowing slow-motion luxury spins (0.1x–0.5x) or high-energy dynamic rotations (2.0x–10.0x).

Background Customization

• Transparent (Free & Pro): Seamlessly integrates into your store's native background.
• Solid Color (Free & Pro): Custom hex color with a real-time color picker.
• Background Gradients & Image Backdrops (PRO ONLY): Exclusive to Models3D Studio Pro. Configure dual-tone linear gradients with custom angular orientation (0° to 360°), cinematic radial studio vignettes, or upload high-resolution lifestyle photography backdrops anchored directly behind the 3D model.

3D Model Workspace & Inspection

The 3D Model Workspace serves as an asset inspection center and model manager:

• Real-Time Model Metrics: Instant display of active file name, total detected mesh layers (e.g. 70 detected layers), and direct file storage URLs.
• Replace or Upload Asset: Upload a new .glb or .gltf asset directly without losing previously configured attribute variations.
• Danger Zone Model Management: Permanently delete the assigned 3D asset, camera presets, and mesh mappings from the WooCommerce product in a single guarded click.
• Starter 3D Model Library: One-click switching between the bundled High-Performance Sports Car, Athletic Sneaker, and Designer Sunglasses starter models.

Interactive Viewport Selection (Point-and-Click)

Instead of searching through endless lists of technical mesh names, the Visual Editor features Raycast Point-and-Click Mesh Selection directly on the 3D canvas.

How Point-and-Click Mapping Works

1. Real-time Hover Highlighting: Move your cursor over any part of the 3D model in the viewport. The hovered mesh layer will illuminate in real time.
2. Direct Click Selection: Click directly on the part of the model you want to customize (e.g., the shoe laces or watch bezel). The selected mesh lights up with a bright blue emissive highlight.
3. Map 3D Mesh Modal: A quick-link modal immediately pops up asking:

   "You clicked: [Mesh Name]. Which WooCommerce attribute controls this part?"

4. Instant Binding: Select the WooCommerce attribute from the dropdown and click Link Attribute. The mesh is immediately bound to that attribute's variations without any manual searching.

3D Material Mappings & Variations

The editor bridges WooCommerce product variation options (e.g. "Colorway: Midnight", "Strap: Leather") directly to physical 3D mesh properties.

Important: Attribute Setup Workflow

Because the visual editor maps WooCommerce attributes to 3D mesh layers, you must follow this workflow:

1. Go to the Attributes tab in the Product Data box, add your attributes (e.g. Color) and terms (e.g. Red, Blue).
2. Click the native WordPress Save Attributes / Update button to commit them to the database.
3. Open the 3D Studio tab and click Launch Visual Editor. The editor will now load all saved attribute terms.

Single vs. Multi Mesh Selection Mode

At the top right of each variation card, you can toggle between two selection modes:

• Single Mode: Modifies exactly one mesh layer per rule for pinpoint component adjustments.
• Multi Mode: Select multiple mesh layers simultaneously. Any material property change (and Pro visibility toggle) will apply to all selected meshes at once (ideal for changing 20 screws or metal rings in one click).

Variation Action Types

Models3D Studio organizes product customization into two specialized channels:

• Material Swap (🎨 Free & Pro): Change Base Color (hex picker), Roughness (matte vs glossy), and Metalness (non-metal vs solid metal) on targeted mesh layers.
• Mesh Layers Visibility Toggles (👁️ PRO ONLY): Completely show or hide targeted meshes when a specific option is chosen (perfect for modular components like laces, outsoles, wheels, and spoilers). In the Free Community Edition, variation cards display an interactive preview teaser card; upgrading to Models3D Studio Pro unlocks full visibility rules and the in-viewport 🎯 Pick 3D raycasting tool.

Camera Views: Scale-Aware Auto-Framing

Proper camera placement is essential for an engaging eCommerce presentation. Models3D Studio pairs automatic scale-aware framing with granular merchant camera controls.

Scale-Aware 3D Auto-Framing Engine

Different 3D models vary drastically in size: a piece of jewelry might measure 20 millimeters, while a sports car measures 4.5 meters. Without scale calibration, small models appear as invisible specks and large models clip violently through the camera lens.

Models3D Studio solves this via dynamic geometric bounding-sphere analysis:

1. Bounding Sphere Math: On asset load, computeAutoFrame computes the exact geometric center and bounding radius ($R$) of the entire mesh hierarchy.
2. Trigonometric Distance Calculation: The ideal camera distance ($D_{ideal}$) is computed dynamically from the camera's vertical field of view ($\text{FOV}$) and canvas aspect ratio: $$D_{ideal} = \max\left(\frac{R}{\sin(\text{FOV}/2)}, \frac{R}{\sin(\text{FOV}/2) \cdot \text{Aspect}}\right) \times 1.35$$
3. Dynamic Frustum Calibration: Camera clipping planes are scaled proportionally: $$\text{near} = \frac{D_{ideal}}{200}, \quad \text{far} = D_{ideal} \times 100$$ This prevents near-plane slicing on large assets while preserving depth buffer precision (preventing z-fighting) on small assets.
4. Calibrated Orbit Zoom Limits: Min/max zoom limits are dynamically bounded ($\text{minDistance} = D_{ideal} \times 0.15$, $\text{maxDistance} = D_{ideal} \times 10.0$).
5. ContactShadows Isolation: Ground contact shadows are decoupled from bounding-box centering calculations to prevent 10-meter ground planes from biasing the auto-frame center.

Merchant Camera Controls

• Capture Current View (Global View): Located in the top environment settings bar. Captures the initial viewpoint when customers load the product page. Marked as is_custom: true in the configuration so auto-framing never overwrites your deliberate choice.
• Save View (Variation-Specific): Located inside each variation card. Saves a swooping camera angle tied to that specific variation (e.g. zooming in on sneaker laces when "Laces" is selected).
• Resetting Camera on Model Replacement: Replacing or switching a 3D model automatically resets custom camera captures, allowing the new asset's auto-framing calculations to take effect cleanly.

Floating Viewport Controls

The 3D canvas includes sleek floating action controls designed for frictionless interaction:

• Reset Camera: Smoothly glides the camera back to the initial auto-framed or merchant-captured viewpoint with orbital easing.
• Fullscreen: Expands the 3D viewport into an immersive full-browser presentation mode for distraction-free styling and client reviews.

Instant Scene Cloning & Developer JSON Suite PRO

PRO EXCLUSIVE TOOLING

Instant Scene Cloning & Developer JSON Suite is an exclusive feature of Models3D Studio Pro.

In the Free Community Edition, the studio operates in a streamlined visual mode with an inline developer teaser card (.m3ds-pro-trigger-json). Upgrading to Models3D Studio Pro activates the live Monaco-style code editor with two-way bidirectional synchronization, real-time schema validation, and instant cross-product JSON cloning.

For technical artists, agency developers, and experienced power users, Programmatic JSON Code Mode provides complete programmatic control over the 3D scene.

Two-Way Bidirectional Synchronization

• Visual Controls to JSON: Adjusting sliders, colors, or toggles in the visual dashboard instantly updates the JSON payload in real time.
• JSON to Visual Controls: Editing values or pasting JSON code automatically updates the visual sliders and variation cards.
• Live 3D Viewport Binding: Changes made in either mode are instantly reflected live in the 3D canvas without page reloads.

Advanced Capabilities Beyond the UI

• Emissive Glow & Intensity: Add self-illuminating glowing materials (e.g. RGB LEDs, headlights) via "emissive": "#00ffcc" and "emissiveIntensity": 2.5.
• PBR Texture Map Swapping: Assign external normal_map_url and roughness_map_url textures.
• Camera Zoom Boundaries: Define strict min/max zoom limits (min_distance, max_distance).
• Custom CDN HDRIs: Direct URL targeting for external high-resolution HDR environment maps.

Real-Time Schema Validation & Syntax Protection

The embedded code editor continuously runs real-time JSON schema validation and syntax checking:

• Instant Error Highlighting: Syntax errors (e.g., trailing commas, unclosed brackets, missing property quotes) are immediately flagged with red warnings in the code margin.
• State Integrity Protection: If JSON syntax is invalid or violates schema types, the Apply Changes to 3D Viewer button is automatically disabled, preventing corrupted or malformed payloads from committing to WooCommerce post-meta.

Universal Import & Export

• Product Cloning: Copy the JSON payload from one product and paste it into any other product sharing the same 3D model to replicate all settings, lighting, and variation rules in seconds.
• Safe Backups: Copy and store JSON blocks in your version control or project notes as instant recovery points.

Models3D Studio Pro

Upgrading to Models3D Studio Pro transforms your WooCommerce store into an enterprise-grade 3D product configurator suite, unlocking 5 core exclusive capabilities:

1. Custom .HDR studio lighting & brand reflections: Upload proprietary .hdr files directly to the WordPress Media Library with independent 360° spin and dynamic exposure calibration.
2. Mesh layers visibility toggles: Channel 2 dual-channel configurators with dynamic Show/Hide rules per variation and in-viewport 🎯 Pick 3D raycast targeting.
3. The 3D model rotation speed control: Precision velocity tuning from 0.1x slow-motion luxury spins up to 10.0x dynamic showcase presentations.
4. Background gradients & image backdrops: Multi-stop linear gradients, radial studio vignettes, and high-resolution lifestyle photography canvas backdrops.
5. Programmatic JSON Code Mode & live sync: Live bidirectional synchronization between code and viewport, real-time schema validation, and instant product cloning.

Free vs Pro Feature Comparison

Capability	Free Community Edition	Models3D Studio Pro
Custom .HDR Studio Lighting & Brand Reflections	❌ 10 Built-in Drei Presets only	✅ Upload custom .hdr files, dynamic exposure & 360° spin
Mesh Layers Visibility Toggles	❌ Interactive Preview Teaser Card	✅ Dynamic Show/Hide rules per variation & 🎯 Pick 3D raycasting
The 3D Model Rotation Speed Control	❌ Standard Fixed 1.0x Velocity	✅ Precision 0.1x to 10.0x velocity calibration
Background Gradients & Image Backdrops	❌ Transparent & Solid Color only	✅ Linear & Radial gradients + High-Res Photo backdrops
Instant Scene Cloning & Developer JSON Suite	❌ Informational Developer Teaser Card	✅ Live bidirectional sync, editing, schema validation & cloning
PBR Material Swaps	✅ Included (Color, Roughness, Metalness)	✅ Included (with advanced clearcoat & transmission)
PBR Quick Presets	✅ Included (Car Paint, Carbon, Chrome, Glass, Rubber, Gold)	✅ Included
Keep Original Material	✅ Included (1-click artwork preservation)	✅ Included
Drei Studio Lighting Presets	✅ 10 Built-in Environments	✅ 10 Built-in Environments + Custom .HDR Uploads
Ground Contact Shadows	✅ Included (Disabled by default for 60fps)	✅ Included
Automatic Cookie Healing	✅ Included in v1.1.3	✅ Included in v1.1.3
WASM Draco Optimizer	✅ Included (Client-side retopology)	✅ Included
Support & Updates	Community Forums	Priority Developer Support & Cloud Updates

---

Pro: Custom .HDR Studio Lighting & Brand Reflections

While the Free Community Edition provides 10 high-quality Drei presets, commercial brands often require proprietary studio lighting or branded reflections that match real-world photoshoot setups.

• Native Media Library Integration: Click Upload Custom .HDR to launch the WordPress media modal and select any .hdr equirectangular lighting file.
• Dynamic Light Exposure: Calibrate lighting brightness to match physical studio lux ratings without clipping white highlights.
• 360° Environment Rotation: Spin the HDRI environment independently of camera orbits to position specular highlights and reflections precisely where they accentuate product contours.

---

Pro: Background Gradients & Image Backdrops

Elevate product presentation beyond plain solid colors with editorial-grade canvas backdrops:

• Linear Gradients: Configure dual-tone linear color transitions with custom angular orientation (0° to 360°).
• Radial Gradients: Create cinematic vignetted studio lighting that draws focus directly to the product center.
• High-Resolution Photo Scenes: Upload custom lifestyle photography or atmospheric studio renders directly to the canvas backdrop. The 3D model stays anchored in 3D space with matching lighting perspective.

---

Pro: Mesh Layers Visibility Toggles

For stores selling modular products, customizable accessories, or multi-part machinery, Pro introduces Channel 2: Dynamic Mesh Layers Visibility Toggles:

• Build Interactive Configurators: Instead of swapping simple colors, you can show or hide physical geometry per variation term (e.g. adding a roof rack to an SUV, swapping high-top laces for sport laces, or alternating platform outsoles).
• 3D Viewport Raycasting Picker: Click directly on any mesh component in the 3D canvas to immediately add it to the variation's Shown or Hidden list.
• Cascading Multi-Attribute Logic: When a customer selects both Finish: Carbon and Package: Aero Spoiler, the 3D canvas resolves both rules simultaneously.

🎯 Pick 3D Viewport Tool Mechanics

Models3D Studio features an intuitive in-viewport picking tool designed for rapidly tagging modular mesh components without searching through technical layer names:

1. Activation via Toggle Button: Inside any variation card's Visibility accordion, click the 🎯 Pick 3D button next to the Show or Hide tag list. The button dynamically transitions to ✕ Stop Pick.
2. Interactive HUD Banner: Activating pick mode mounts a persistent HUD banner (.m3ds-canvas-pick-hud) along the bottom edge of the 3D viewport displaying:
   • A pulsing status dot indicating the active operation.
   • Clear operational guidance (e.g. Click parts to Hide for Midnight).
   • An instant Done (ESC) button to exit.
3. Contextual Viewport Highlighting & Cursors:
   • The body cursor automatically morphs into a precision crosshair.
   • Show Mode: Hovering and clicking meshes illuminates them with a crisp emerald green outline and pulse (#10B981).
   • Hide Mode: Hovering and clicking meshes illuminates them with a vibrant crimson red outline and pulse (#EF4444).
4. Opposing List Auto-Deduplication: If a mesh is currently marked in the "Hide" list and you pick it in "Show" mode, the tool automatically purges it from "Hide" and transfers it to "Show" (and vice-versa), eliminating configuration conflicts.
5. Material-Channel Collision Protection: The editor enforces a strict validation guard between Channel 1 (Material Swaps) and Channel 2 (Visibility Overrides) (admin-init.js#L1157-L1169). If you attempt to hide a mesh layer that is currently assigned as an active Target Mesh Layer under Channel 1 for that variation, the action is intercepted with an Invalid Action notification. You cannot hide a mesh layer while actively applying PBR material rules to it.
6. Frictionless Exit: You can exit pick mode at any moment by pressing the Escape key on your keyboard, clicking the Done (ESC) button on the canvas HUD, or clicking the ✕ Stop Pick toggle button. The viewport immediately restores default camera orbit controls.

---

Pro: The 3D Model Rotation Speed Control

Auto-rotation showcases products from every angle. In Models3D Studio Pro, the 3D model rotation speed control unlocks velocity calibration to match your product category:

• Slow-Motion Luxury Spin (0.1x – 0.5x): Ideal for jewelry, luxury watches, and high-end footwear where buyers need time to inspect subtle facet reflections.
• Standard Showcase Spin (1.0x): The default natural presentation velocity.
• High-Speed Dynamic Preview (2.0x – 10.0x): Perfect for automotive wheels, turbines, and dynamic sportswear demonstrations.

---

Pro: Programmatic JSON Code Mode & Live Sync

Directly inspect, edit, and validate the raw 3D scene JSON specification stored in WordPress post-meta with full two-way live synchronization:

• Bidirectional Live Sync: Edit colors, camera vectors, or mesh names in JSON, click Apply Changes to 3D Viewer, and observe the 3D scene update instantaneously.
• Schema Validation: Built-in syntax error protection prevents corrupted payloads from saving to WooCommerce post-meta.
• Instant Product Cloning: Copy the JSON payload from one product and paste it into any other product sharing the same 3D model geometry to replicate entire variation setups in seconds.

---

Pro: Instant License Activation & Upgrades

Models3D Studio Pro integrates seamlessly with Freemius Cloud licensing:

• Informational Capability Modals: Clicking any Pro teaser card inside the Visual Editor opens the informational Pro Feature Modal (showProFeatureModal), providing direct upgrade links to the official studio checkout with launch pricing applied.
• Seamless Upgrade Migration: When upgrading from Free to Pro, existing product configurations, camera captures, and material mappings are 100% preserved.
• Silent Sibling Deactivation: In v1.1.3, activating Pro automatically deactivates the Free edition cleanly with zero fatal redeclaration errors.

3D Asset Optimization & Guidelines

WebGL on mobile devices has strict memory and processing constraints. Following clean asset guidelines ensures fast load times and smooth 60 FPS performance across all devices.

The 250,000 Vertex Limit

• Absolute Maximum: 250,000 vertices.
• The device type (desktop, tablet, mobile) is irrelevant—the plugin strictly enforces a 250k ceiling.
• Any model exceeding 250,000 vertices will be intercepted by the Pre-Flight Inspector upon upload.

Load Time Target

Keep initial 3D model download sizes under 5MB (ideally < 2MB) to ensure sub-3-second load times on mobile 4G/5G connections.

Built-in WASM Draco Optimizer

Models3D Studio includes a client-side WebAssembly (WASM) geometry optimizer powered by Google Draco algorithms.

Two-Stage Optimization Flow

When an uploaded 3D model exceeds 250,000 vertices, the editor intercepts it with the Model Too Heavy modal:

Stage 1: Safe Optimization

• Click Proceed with Optimization.
• The WASM engine automatically compresses and retopologizes the geometry in your browser without causing visual distortion.

Stage 2: Force Crunch (Extreme Compression)

• If the Safe Optimizer stops to protect mesh topology but the vertex count is still above 250,000, you will be prompted with two choices:
  1. Abort (Fix in Blender): Recommended for complex CAD models to manually decimate in your 3D software.
  2. Force Crunch Anyway: The WASM engine aggressively decimates polygons until the vertex count falls below 250k. (Note: extreme crunching may cause visible artifacts on fine details).

Texture Baking & Draco Compression

Texture Guidelines

• Resolution: Never upload raw 4K (4096x4096px) textures to the web. Bake textures to 2048x2048 (2K) or 1024x1024 (1K).
• Format: Use JPG or WebP for opaque base color maps. Use PNG only when transparency (alpha channel) is strictly required.
• Atlasing: Combine multiple materials into a single texture atlas to minimize WebGL draw calls.

Exporting with Draco Compression

When exporting .glb models from Blender, 3ds Max, Maya, or Cinema 4D:

• Enable the Apply Draco Compression checkbox.
• Draco compresses geometry and vertex arrays, reducing file sizes by up to 80% with zero visual quality loss.
• Models3D Studio includes a high-speed WASM Draco decoder to decompress assets on the fly.

Frontend DOM Event Bridge

When customers select variation dropdowns or color swatches on your WooCommerce product page, the 3D canvas instantly morphs to match the selected option with smooth orbital physics.

Models3D Studio emits standard DOM events from the React Three Fiber canvas and the bidirectional EventBridge, allowing developers to listen to 3D state changes from Vanilla JavaScript or jQuery.

Listening to 3D Events

// 1. Canvas Ready & Initial Mount
// Listen for canvas readiness, or verify the synchronous boolean if code runs after mount
if (window.__woo3dCanvasReady) {
    console.log('3D Canvas already initialized and active');
}
window.addEventListener('woo3d_canvas_ready', function() {
    console.log('3D Canvas and WebGL context successfully mounted');
});

// 2. Individual Attribute Changed (Select dropdown, radio button, or color swatch)
window.addEventListener('woo3d_attribute_changed', function(e) {
    console.log('Attribute changed:', e.detail.attribute_name, '=>', e.detail.value);
    console.log('Active attribute set:', e.detail.all_attributes);
});

// 3. Complete Variation Matched & Shown
window.addEventListener('woo3d_variation_shown', function(e) {
    console.log('WooCommerce variation matched:', e.detail.variation);
    console.log('All selected attributes:', e.detail.all_attributes);
});

// 4. Variation Hidden (Partial or incomplete attribute combination)
window.addEventListener('woo3d_variation_hidden', function(e) {
    console.log('Variation hidden event:', e.detail.event);
    console.log('Remaining attributes:', e.detail.all_attributes);
});

// 5. Variations Reset (Customer clicked WooCommerce "Clear" variations button)
window.addEventListener('woo3d_variations_reset', function() {
    console.log('Variations reset to default model baseline');
});

// 6. Interactive Mesh Clicked on Storefront
window.addEventListener('woo3d_frontend_mesh_clicked', function(e) {
    console.log('Customer clicked mesh node:', e.detail.meshName);
});

Backend PHP Filters Reference

Extend and customize plugin behavior using standard WordPress filter hooks:

Custom Template Override Filter

Override the default 3D gallery template path from your theme or child plugin (GalleryArchitect.php#L721):

add_filter( 'models3d_locate_template', function( $template, $template_name, $template_path, $default_path ) {
    // Override template location for custom theme integrations
    if ( 'product-image-override.php' === $template_name ) {
        $custom_template = get_stylesheet_directory() . '/models3d-studio/' . $template_name;
        if ( file_exists( $custom_template ) ) {
            return $custom_template;
        }
    }
    return $template;
}, 10, 4 );

Inflate AJAX Variation Ceiling

For configurable products with complex variation matrices (e.g., 50+ attribute permutations), raise the WooCommerce AJAX threshold to prevent fallback to heavy server-side checks:

add_filter( 'woocommerce_ajax_variation_threshold', function( $threshold ) {
    return 500; // Increase threshold for complex 3D configurators
} );

Staging & Local License Testing

Local and staging license testing is handled natively through Freemius Cloud under WooCommerce -> 3D Studio -> License. Staging sites and localhost environments can activate development licenses without custom server constants.

Configuration JSON Schema Specification

The complete 3D scene state, camera coordinates, and variation bindings are stored in the WordPress wp_postmeta table as serialized JSON under _models3d_studio_config.

Example Payload Structure

{
  "product_id": 476,
  "model_url": "https://example.com/wp-content/uploads/2026/08/sneaker.glb",
  "preflight_metadata": {
    "has_uv_maps": true,
    "vertex_count": 28450,
    "file_size_bytes": 1048576,
    "draco_compressed": true
  },
  "camera_settings": {
    "target": [0, 0, 0],
    "position": [0, 1.5, 3.5],
    "fov": 45,
    "min_distance": 0.5,
    "max_distance": 15,
    "is_custom": true,
    "captured": true
  },
  "environment_settings": {
    "preset": "studio",
    "intensity": 1.2,
    "shadows_enabled": false
  },
  "mappings": [
    {
      "attribute_taxonomy": "pa_color",
      "target_mesh_nodes": ["Sneaker_Sole", "Sneaker_Laces"],
      "control_type": "material_property",
      "variations_map": [
        {
          "term_slug": "midnight",
          "visibility_rules": {
            "enabled": true,
            "hide": ["Accessory_Strap"],
            "show": ["Sole_Accent"]
          },
          "payload": {
            "color": "#111827",
            "roughness": 0.35,
            "metalness": 0.1,
            "emissive": "#000000",
            "emissiveIntensity": 1
          }
        }
      ]
    }
  ]
}

WebGL Diagnostics

Click the button below to simulate sending a secure diagnostic payload to the parent WooCommerce panel.

Common Troubleshooting

Model Fails to Load or Black Canvas

1. Check File Format: Ensure your model is a valid .glb (binary) or .gltf file.
2. Inspect Pre-Flight Warnings: Check if the model exceeded 250,000 vertices.
3. Check WebGL Support: Visit the WebGL Diagnostics page in the documentation to verify hardware acceleration.

Mobile Safari Performance Issues

1. Reduce texture resolutions from 4K down to 1K or 2K.
2. Ensure textures are saved in JPG or WebP formats.
3. Use the built-in WASM optimizer or export with Draco compression.

Sandboxed Iframe Warnings

Console notices regarding iframe sandboxing (allow-scripts and allow-same-origin) are harmless security indicators confirming that documentation is safely isolated from administrative operations.

REST API Uploads & Cookie Check Auto-Healing

When uploading custom 3D models (.glb / .gltf) or HDR environment maps, WordPress REST API requests can occasionally fail with a 403 Forbidden ("Cookie check failed") or rest_cookie_invalid_nonce error. This is a common WordPress core issue caused by browser cookie shadowing across differing paths (e.g., / vs /wp-admin/) or multiple concurrent admin sessions.

In v1.1.3, Models3D Studio introduces an automated session auto-healing mechanism (m3ds_auto_heal_duplicate_session_cookies hooked into determine_current_user and init):

• Collision Detection: The filter inspects $_SERVER['HTTP_COOKIE'] for duplicate LOGGED_IN_COOKIE tokens.
• Validation: Each duplicate cookie is verified using WordPress core's wp_validate_auth_cookie().
• Transparent Recovery: When a valid session is identified, $_COOKIE is corrected and the authenticated user ID is restored before the REST authentication handler executes. Media uploads proceed smoothly without requiring users to clear browser cookies or log in again.

CORS & CDN Configuration

Tainted Canvas & Cross-Origin Errors

When loading 3D assets, textures, or HDR environment maps from an external Content Delivery Network (Amazon S3, Cloudflare, bunny.net, or a media subdomain), the browser requires Cross-Origin Resource Sharing (CORS) permission.

Without CORS headers, WebGL will throw a security error and refuse to render the model.

The Solution

Configure your CDN or server to return the following HTTP header for 3D file extensions (.glb, .gltf, .hdr, .bin):

Access-Control-Allow-Origin: *

Apache (.htaccess)

<FilesMatch "\.(glb|gltf|hdr|bin)$">
    Header set Access-Control-Allow-Origin "*"
</FilesMatch>

Nginx (nginx.conf)

location ~* \.(glb|gltf|hdr|bin)$ {
    add_header Access-Control-Allow-Origin *;
}

Uninstallation & Data Privacy

Models3D Studio adheres to WordPress.org data retention and privacy best practices.

Default Lifecycle Behavior

By default, deactivating or uninstalling the plugin preserves your 3D product configurations (_models3d_* post-meta) in the database. This guarantees that your 3D variation mappings, camera angles, and lighting presets are safely retained during plugin updates or temporary site maintenance.

Opt-In Complete Data Erasure

For merchants requiring strict compliance with data privacy regulations (e.g. GDPR) or those wishing to leave no residual database footprint:

1. Navigate to WooCommerce -> 3D Studio -> Settings in your WordPress admin.
2. Enable the Erase all 3D Studio data on uninstallation toggle (models3d_erase_data_on_uninstall).
3. Save settings.

When this setting is active, deleting the plugin via WordPress Admin triggers uninstall.php, which executes a clean SQL purge removing all plugin post-meta and options from the database.