One-click Cycles → Octane scene conversion for Blender

Interface • Features • How It Works • Supported Nodes • Installation

---

Octanify translates supported Cycles materials, lights, and World environments into Octane graphs while preserving the original renderer branches. The current workspace is a hardened release candidate: inspect its per-item conversion report for approximations and unsupported paths. Broader render, performance, installation, and compatibility certification remains tracked in the execution ledger.

Convert supported branches without routine rewiring, preserve the Cycles source, and inspect approximations or fallbacks in one structured report.

---

📑 Table of Contents

• 🖥️ The Interface
• 📖 How to Use Octanify
• ✨ Features
• 🎬 Animation and Semantic Value Transfer
• 🛡️ Recovery, Refresh, and Ownership
• 💡 Lights and World Environments
• 🎨 Destination-Aware Texture Intent
• ⚠️ Current Support Limits
• 🛠️ Workflow Utilities
• ⚙️ How It Works
• 🔌 Supported Nodes
• 📁 Project Structure
  • Validation
  • Headless conversion
• 📥 Installation
  • Blender 4.2+
  • Requirements
  • Runtime-verified configuration and compatibility note
• 🙏 Credits
• License

---

🖥️ The Interface

Once installed, press N in the 3D Viewport or Shader Editor and open the Octanify tab. The interface uses a compact control-deck layout: conversion stays at the top, common material and node tools remain immediately accessible, and advanced details start collapsed.

┌──────────────────────────────────────────┐
│ ▼ Octanify                               │
│ ┌──────────────────────────────────────┐ │
│ │       [ CONVERT TO OCTANE ]          │ │
│ │ Objects to Convert                   │ │
│ │ [ Active Object ] [ Entire Scene ]   │ │
│ │ Selection + active object's children │ │
│ │ [ Materials ] [ Lights ] [ World ]   │ │
│ │ [ ] Local Copies for Selected Objects│ │
│ │ [x] Keep Original Cycles Nodes       │ │
│ │ Octane Material                      │ │
│ │ [ Standard Surface (Recommended)  ▼ ]│ │
│ │ Recommended - closest Principled match│ │
│ │ [ ] Auto-upgrade SSS to Standard     │ │
│ │ [ Arrange Nodes ] [ Color Nodes ]    │ │
│ │ ✓ Last conversion completed          │ │
│ └──────────────────────────────────────┘ │
│                                          │
│ ┌──────────── Albedo Gamma ────────────┐ │
│ │ [ gamma slider                      ]│ │
│ │ [ Selected Material ] [ All Materials]│ │
│ └──────────────────────────────────────┘ │
│                                          │
│ ┌────────────── Node Tools ────────────┐ │
│ │ [ Preview / Restore Node            ]│ │
│ │ [ Refresh Converted Branch          ]│ │
│ │ [ Arrange Current Node Tree         ]│ │
│ │ [Create Material] [Connect Textures] │ │
│ │ [ Delete Cycles Nodes               ]│ │
│ └──────────────────────────────────────┘ │
│                                          │
│ ▶ Displacement Settings                  │
│ ▶ Conversion Report                      │
└──────────────────────────────────────────┘

During conversion, the completion message is replaced by a live percentage bar and the current operation. Once complete, the bar collapses back to a quiet status line so it does not compete with the main action.

📖 How to Use Octanify

1️⃣ Conversion Console

The large Convert to Octane action is always the first control. The conversion choices sit directly beneath it:

• Active Object converts materials discovered on selected objects plus every descendant of the active object. This includes materials assigned by nested Geometry Nodes Set Material nodes and supports parent/empty-based production assets whose root object has no material slots.
• Entire Scene scans direct scene objects, material slots, and Geometry Nodes material references; it does not traverse collection-instance source data.
• Materials, Lights, and World preserve the legacy default of enabling all three domains. Materials follow the object scope; Lights remain scene-wide and World means the current scene World.
• Local Copies for Selected Objects isolates assignable selected slots in Active Object mode. Shared mesh data and Geometry Nodes references are skipped with disclosure. Shared datablocks are converted in place by default and outside users are reported. Linked/non-editable IDs are skipped; Octanify does not create library overrides or make libraries local.
• Keep Original Cycles Nodes is enabled by default. Disabling it deletes source nodes after a completed committed conversion, including approximate results with warnings. Failed or cancelled conversions retain their source.
• Octane Material chooses what each Cycles Principled BSDF becomes. Standard Surface is recommended because its separate base, specular, transmission, coat, sheen, and subsurface controls most closely match Principled semantics. Universal Material remains available for compatibility and uses the plain GGX BRDF model—not Octane or GGX (energy preserving). Glossy Material provides the classic Octane diffuse/specular workflow and reports Principled lobes it cannot represent instead of wiring them into unrelated sockets.
• OpenPBR Surface (Experimental) is an additional explicit target for compatible Octane builds. It maps independent physical layers, thin-film units, constant SSS radius, and internal/Blackbody emission. Missing OpenPBR support fails clearly instead of substituting another material. Enable Keep Original Cycles Nodes to retain the source for review; unchecked also removes it after completed OpenPBR conversions with warnings. Standard Surface remains the default.
• Auto-upgrade SSS materials to Standard Surface is an optional, disabled-by-default safety override. When enabled, a Principled material with active subsurface intent uses Standard Surface even if Universal or Glossy was selected; every override appears in the conversion report.
• Arrange Nodes controls automatic dependency-based layout after conversion, including nested frame contents and converted node groups.
• Color Nodes independently controls the graphite/teal editor themes. Disable it to retain Blender's default node colors without disabling layout or graph tagging.

The same action also detects supported Cycles lights anywhere in the scene and the active World. By default, conversion preserves the authored Cycles branches while creating separate Octane outputs. Re-running conversion skips unchanged generated light/World graphs, detects supported source-property changes, and upgrades older generated graphs when possible. Artist-authored native Octane light/World roots are excluded from automatic conversion.

2️⃣ Live Progress

The progress bar appears only while conversion is running. Material conversion and layout run in cooperative steps. Esc closes the active iterator, rolls back the partial conversion, and keeps completed items undoable; switching the originating scene also stops the job. Queued timer events cannot restart an aborted job. Settings and material work items are captured when the job starts, so mid-job panel changes do not change that plan. Large-graph cancellation is verified on the validated host, not a latency guarantee for arbitrary scenes or scene-domain work.

3️⃣ Albedo Gamma

The visible gamma control handles a common post-conversion adjustment without opening another panel. Change the slider, then choose Selected Material or All Materials to update existing Octane textures without reconverting. These actions also repair older owned data textures from their recorded source encoding; the artistic gamma slider itself affects color roles, not roughness or other data roles.

4️⃣ Node Tools

Frequently used node actions stay together in a compact tool group:

• Preview / Restore Node temporarily routes a node through an owned emission preview without changing the Cycles connection, then restores the prior Octane connection. Restoration survives save/reopen and source renaming.
• Refresh Converted Branch detects source, nested-group, animation, and setting changes; unchanged graphs are skipped. A replacement is staged before material users are remapped. Generated artist edits need explicit replacement permission, while missing sources or unowned native additions cause safe refusal. Failed staging leaves the previous result intact.
• Arrange Current Node Tree immediately arranges the material, World, light, or nested node-group tree currently open in the Node Editor.
• Create Material creates a clean material using the selected Octane material type.
• Connect Textures fills empty destinations by filename patterns, reports ambiguous packed textures, and requires explicit replacement to overwrite occupied links.
• Delete Cycles Nodes removes only Cycles nodes explicitly tagged by Octanify for the current Active Object or Entire Scene choice. Original Cycles nodes remain preserved by default, and cleanup asks for confirmation and supports Blender Undo.

5️⃣ Displacement Settings

Open this subpanel only when the defaults need adjustment:

• Mode selects the node class created for a Cycles Displacement node: Octane Texture Displacement for image/procedural height fields or Octane Vertex Displacement for displacement evaluated on mesh vertices and subdivision.
• Level of Detail is shown only in Texture mode and sets that node's displacement-map resolution limit.
• Mid Level transfers from the Cycles node by default. Setting a non-default panel value applies it as the conversion-wide zero-point override.

This preference is consumed while nodes are created; it is not a display-only setting. The Blender 5.1 + Octane 31.9 runtime validator checks that the two modes produce OctaneTextureDisplacement and OctaneVertexDisplacement, respectively.

6️⃣ Conversion Report

Open this subpanel to inspect per-material, light, and World clean/approximate/failed/skipped/cancelled outcomes, cleanup eligibility, approximations and warnings. Messages are searchable without a five-message truncation and can be exported as JSON or text; reports are bound to the scene/job. Item actions select material users or the relevant light. Reports include issue codes, captured settings, timing, and runtime material candidates. Light/World failures count as failed items, not merely global warnings.

✨ Features

Feature	Description
🎯 Principled BSDF Targets	Fidelity-first Standard Surface mapping, physically tuned Universal compatibility mapping, or a narrower classic Glossy Material workflow with explicit unsupported-lobe reporting
🧪 Experimental OpenPBR	Explicit native OpenPBR target with independent layers, constant SSS decomposition, thin-film unit conversion, and target-specific emission; source retained
🧬 Smart SSS Override	Optionally promotes only Principled materials with active subsurface intent to Standard Surface while leaving the selected target unchanged for other materials
🧠 Shading Intent	Traces destination roles while preserving authored RGB decoding, including sRGB roughness through a ColorRamp; isolates artistic color adjustments from data and alpha paths
🪆 Node Groups	Recursively converts nested Node Groups into cached Octane group datablocks without ungrouping or mutating the authored Cycles groups
🎬 Animation Preservation	Exact socket-path keyframes, supported FCurve modifiers and rebound drivers, including nested groups and shared/layered Action handling; unsupported animation is reported
🎚️ Color-Correction Units	Converts HSV and Brightness/Contrast values into Octane units, disclosing non-equivalent brightness and unsupported negative contrast
🔗 Link Reconstruction	Rebuilds topology with 7-strategy socket matching, shared-node preservation, reroute flattening, and duplicate socket handling
🧭 Graph Engine	Cycle-safe dependency scheduling preserves branching, muted nodes, material outputs, and nested group boundaries
🪟 Glass & Transmission	Converts glass, refraction, alpha, and transmission paths without corrupting unrelated Universal Material defaults
💡 Emission	Auto-inserts Texture Emission for materials with the existing x100 scale and uses Black Body Emission with type-specific power conversion for lights
🌫️ Volumetrics	Applies Octane's 100-based medium-density scale, preserves linked density drivers, merges compatible Absorption + Scatter graphs, and supports volume-only materials through Null Material
🗺️ Normal, Bump & Displacement	Preserves normal chains, folds bump height into material inputs, and creates Texture or Vertex Displacement according to the selected mode
🧩 UV Mapping	Routes coordinates to Projection/UV Transform, converts rotations to degrees with XYZ order, and uses reciprocal Point/Vector Mapping scale
🌀 Procedural Scale Matching	Matches Generated/Object-coordinate procedural scale with object bounds; assignable shared materials receive variants for differing local mesh bounds
🧱 Composite Texture Layers	Rebuilds color Mix/MixRGB nodes as native Composite Texture layers when available, with transactional fallback to legacy Mix nodes
🧬 Geometry Nodes Materials	Discovers Set Material references through nested Geometry Nodes groups and Switch branches, then deduplicates them against normal slots
💡 Scene Lights	Exposure, normalization, cone/size controls, calibrated point/area power handling, staleness detection, and separate outputs; Sun/Spot radiometry remains approximate
🌍 World Environments	Flat-color and HDRI Worlds with strength, encoding-aware image treatment and Mapping Z rotation; unsupported transforms/projections are reported
🎭 Gobos	Converts generic image gobos and Light Wrangler setups, including Alpha, mapping, inversion, animation, focus, and vignette controls
📦 Batch Conversion	Converts selected hierarchies or complete scenes with live progress plus automatic scene-light and active-World detection
🧷 Explicit Scene Scope	Independent Materials/Lights/World switches, shared-user disclosure, optional selected-slot isolation, and linked/non-editable data guards
🔄 Dual Renderer Graphs	Keeps Cycles and Octane material, light, and World branches with renderer-targeted outputs, optional themes, automatic layout, and safe cleanup/migration
🛡️ Transactional Recovery	Rolls back staged graphs, assignments, drivers, cache and unused generated resources on failure; requested source cleanup runs only after completed material conversion
🔄 Safe Branch Refresh	Signature-based change detection, staged replacement, generated-edit permission, and ownership-based refusal instead of deleting artist content
📋 Scene-Bound Reports	Searchable per-domain outcomes, issue codes, JSON/text export, item selection and runtime capability preflight
🖥️ Headless Conversion	Repository tool with JSON reports and explicit clean/degraded/failed exit codes for automation
🧹 Node Arrangement	Ranks dependencies, reduces crossings, packs disconnected components, handles cycles, and arranges nested frame contents without changing graph semantics
🛡️ Structured Fallbacks	Unsupported or approximate conversions stay visible, produce warnings, and do not crash the conversion
🧮 Math & Mix Wrappers	Uses Octane Cycles-compatible wrappers where available, with native fallbacks for plugin-version differences

---

🎬 Animation and Semantic Value Transfer

Supported material socket animation transfers through exact RNA paths, including escaped node names, vector/color components, nested groups, keyframe handles/interpolation, supported FCurve modifiers, and driver variables. Destination paths and driver expressions are rebound to the converted graph; shared Actions are not modified in place, and legacy/layered Actions are handled.

Values are mapped into the destination's semantics instead of copied blindly:

• HSV saturation and value multiply by 100; hue maps as (hue - 0.5) × 2.
• Brightness maps as 100 + brightness. Nonzero brightness is reported as approximate because the operators differ; negative contrast is limited to 0 and reported.
• Mapping rotation converts radians to degrees and uses XYZ Euler order. Point/Vector scale uses 1 / scale, matching the opposite texture-size convention; zero scale is an explicit approximation.
• Principled Specular IOR Level uses the target-specific 2 × level mapping; OpenPBR thin-film thickness converts nanometres to micrometres.

Affine conversions also apply to supported keyframes/drivers. Reciprocal Mapping-scale animation, independently animated Universal/Glossy weight–tint compositions, NLA transfer, and general light/World animation remain unsupported and are reported with source retention. See mapping and animation details.

🛡️ Recovery, Refresh, and Ownership

Conversion stages generated content and commits only after its required work succeeds. Failures restore original graph state and assignments, remove newly unused staged resources, and restore conversion-cache state. Light/World replacement also protects the previous generated branch through late layout failures.

With Keep Original Cycles Nodes unchecked, completed, committed material results authorize automatic Cycles-node deletion, including approximate results with warnings. Failed, cancelled, skipped, or unknown results do not authorize it; light/World source branches are not covered by that checkbox. Warnings remain in the report. The explicit cleanup tool remains scoped, confirmed, and undoable. Keep the source if you intend to review unmapped features, render in Cycles, or use Refresh Converted Branch later.

Preview nodes and refresh deletions are ownership-tagged, not identified by an Octane-looking name. Preview restores the exact prior output link after repeated toggles, Undo/Redo, or save/reopen. Refresh protects externally referenced generated groups, skips unchanged results, and refuses arbitrary mixed native/converted graphs rather than overwriting unowned artist content.

💡 Lights and World Environments

Point/Sun/Spot/Area conversion preserves the supported type-specific controls: source exposure, normalization, area shape/dimensions, point radius, spot cone/blend, Sun angle, and object transform. Point/area power uses the paired-HDR-calibrated transfer, including area-size compensation without changing the authored dimensions. Its calibrated boundary is neutral 6500 K, unit-object-scale emitters on the validated runtime; tinted, temperature-controlled, or scaled emitters, plus Sun/Spot radiometry, are reported as approximate.

Flat-color and HDRI Worlds retain the Cycles branch and transfer strength. HDRI Mapping Z rotation maps to Octane's spherical projection axis. Source signatures detect image encoding, supported light/gobo parameters, and World mapping changes so a later conversion can rebuild stale generated graphs. Non-Z HDRI tilt, translation/scale, non-Point Mapping, and non-equirectangular projection are disclosed rather than silently counted as clean.

Generic image and Light Wrangler gobos transfer supported image/alpha, mapping, perspective projection, inversion, focus, vignette, and frame-playback settings. Image playback support is not general light-node animation transfer.

🎨 Destination-Aware Texture Intent

Octanify combines destination role with the declared source encoding. Authored sRGB RGB outputs use Octane's sRGB transform even when they feed a data input through a ColorRamp or math chain. Valid linear inputs stay linear; authored Non-Color/Raw data and dedicated Alpha images use Non-Color. Installed ACES/OCIO names are matched explicitly. Unknown encodings and role mismatches are reported rather than silently overriding the source. Shared color/data images use separate instances so artistic gamma affects only the color path and never texture Power. Eligible nested generated groups update once; native/source groups remain untouched. See color-policy details.

      [ CYCLES TREE ]                  [ OCTANE TREE ]
  ┌───────────────────┐             ┌───────────────────┐
  │ Color Map (sRGB)  ├─┐         ┌─┤ sRGB transform    │
  └───────────────────┘ │         │ └───────────────────┘
                        ▼         │
               ┌────────┴───┐     │        ┌────────────┐
               │ Principled │ ===>│        │ Standard   │
               │ BSDF       │     │        │ Surface    │
               └────────┬───┘     │        └────────────┘
                        ▲         │
  ┌───────────────────┐ │         │ ┌───────────────────┐
  │ Data Map (Linear) ├─┘         └─┤ Non-Color data    │
  └───────────────────┘             └───────────────────┘

If a color texture needs artistic adjustment later, change the Albedo Gamma slider and click Selected Material to update the active Octane material without reconverting.

---

🛠️ Workflow Utilities

These buttons (located at the bottom of the panel) speed up your daily shader work:

🔗 [ Auto-Connect Textures ]

Dropped a bunch of loose PBR images into the shader editor? Octanify will read the filenames and instantly connect them to the correct sockets based on smart word boundaries (_col, _rough, _nrm, _disp, etc).

In dual-renderer materials it prefers the Octane destination and leaves the Cycles branch unchanged. Empty sockets are filled by default; occupied links require explicit replacement. Failed replacement restores the original link, and displacement creates the required Texture/Vertex Displacement chain. Ambiguous packed ORM/RMA/MRA images are reported and skipped instead of guessed.

 ┌───────────────┐
 │ wood_col.png  ├──────────┐     ┌──────────────┐
 └───────────────┘          └───► │ Albedo Color │
                                  │              │
 ┌───────────────┐          ┌───► │ Roughness    │
 │ wood_rgh.png  ├──────────┘     │              │
 └───────────────┘                │ Universal    │
                                  │ Material     │
 ┌───────────────┐          ┌───► │ Normal       │
 │ wood_nrm.png  ├──────────┘     │              │
 └───────────────┘                └──────────────┘

👁️ [ Preview Node in Viewport ]

Trying to figure out what a complex Math node or ColorRamp is doing? Select it and click Preview. Octanify isolates the node by temporarily routing it through an Emission setup so you can see it glowing in the live Octane viewport.

 ┌───────────────┐             ┌─────────────┐
 │ Complex       │    [👁️]    │ Temporary   │
 │ Noise Pattern ├───►CLICK───►│ Emission    │──► (VIEWPORT)
 └───────────────┘             └─────────────┘

🆕 [ Create Basic Material ]

Creates a fresh, properly wired Octane material using the selected Standard Surface (recommended), Universal, Glossy, or experimental OpenPBR target. The new material is connected to its output; this is not a conversion of an existing artist graph.

🧹 [ Arrange Current Node Tree ]

Arranges the tree currently open in the Node Editor, including nested group-edit contexts. Converted dual-renderer trees keep their Cycles and Octane branches separated; framed graphs are arranged from the deepest frame outward. This action changes editor positions only—it never inserts, removes, ungroups, or rewires shader nodes.

---

⚙️ How It Works

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Analyze    │────▶│    Create    │────▶│   Transfer   │
│  Cycles Tree │     │ Octane Nodes │     │  Properties  │
└──────────────┘     └──────────────┘     └──────────────┘
                                                │
┌──────────────┐     ┌──────────────┐           ▼
│   Apply      │◀────│    Post-     │◀────┌──────────────┐
│   Gamma      │     │   Process    │     │   Rebuild    │
└──────────────┘     └──────────────┘     │    Links     │
                                          └──────────────┘

1. Discover — Collect normal material slots and recursively discover Geometry Nodes Set Material references. The same operator detects supported scene lights and the active World.
2. Trace intent — Walk backward from terminal shader inputs through reroutes and nested groups, recording destination roles per node output path before conversion begins.
3. Analyze — Snapshot the Cycles node tree, normalize reroutes, preserve shared branches, and record properties, links, muted state, outputs, and group boundaries.
4. Schedule and create — Use cycle-safe dependency ordering and runtime-resolved bl_idname candidates to create compatible Octane nodes without ungrouping source groups.
5. Transfer — Target-aware handlers map Cycles values and supported animation into actual Octane material semantics. Standard Surface and experimental OpenPBR receive their independent layer controls, Universal receives scaled/composed equivalents, and Glossy receives only compatible classic controls. The optional SSS override is resolved per material before creation.
6. Rebuild — Seven-strategy socket resolution reconnects duplicate socket identities, output indices, one-to-many channel picker bindings, and split Projection / UV Transform paths.
7. Post-process — Fix Mix Shader order, expand supported color mixes into Composite Texture layers, insert emission nodes, apply destination-aware gamma, handle opacity/Alpha, Normal/Bump, displacement, 100-based medium density and volume topology, mixed-role texture duplication, and object-aware procedural scale matching.
8. Convert scene domains — Build renderer-targeted Octane light and World branches, including supported gobos, only after complete replacement graphs validate successfully.
9. Style and report — Optionally color and arrange both renderer graphs, report live progress and approximations, and leave recoverable failures visible for manual review.

---

🔌 Supported Nodes

The full support matrix lives in octanify/NODE_SUPPORT.md. It currently tracks 99 Cycles node entries plus dedicated scene-domain conversion:

• 84 supported or preserved: 44 direct, 36 approximate, 3 version-dependent, and 1 layout-only.
• 15 unsupported: 13 unsupported and 2 unsupported in the current Octane plugin.
• Section coverage: Input 13/20, Output 3/4, Shader 23/24, Texture 13/15, Color 6/7, Vector 8/9, Converter 14/15, Script/Group 4/5.
• Scene domains: Point/Sun/Spot/Area lights, flat/HDRI Worlds, generic gobos, and Light Wrangler gobos.

Shaders (23 supported / 24 tracked)

• Principled BSDF → Standard Surface by default / Universal or Glossy Material option, with an optional per-material SSS upgrade to Standard Surface
• Principled BSDF → OpenPBR Surface as an explicit experimental option on compatible registered Octane builds
• Glass BSDF → Specular Material
• Glossy BSDF → Glossy Material
• Diffuse BSDF → Diffuse Material
• Metallic BSDF → Metallic Material
• Toon BSDF → Toon Material
• Sheen BSDF → Universal Material
• Hair BSDF / Principled Hair → Hair Material
• Subsurface Scattering (standalone) → Universal Material
• Emission → Diffuse Material + Texture Emission, including colored/textured zero-strength intent detection
• Transparent BSDF → Null Material
• Translucent BSDF → Diffuse Material
• Refraction BSDF → Specular Material
• Holdout / Ray Portal / Background → Support mapped
• Mix Shader / Add Shader → Mix Material (with auto slot swap)

Textures (13 supported / 15 tracked)

• Image Texture → Octane Image Texture (with strict colorspace/packed-file handling)
• Environment / Sky Texture → Octane Image / Daylight Env
• Noise / Musgrave → Cinema 4D Noise when available, including Generated/Object-coordinate scale matching
• Voronoi → Cinema 4D Voronoi when available, including Generated/Object-coordinate scale matching
• White Noise → Octane Noise fallback
• Wave → Octane Wave
• Checker → Octane Checks
• Brick / Magic → Octane Marble
• Gradient → Octane Gradient

Input / Vector (21 supported / 29 tracked)

• Mapping → UV Transform; Vector Rotate / Transform → approximate 3D Transform
• Texture Coordinate / UV Map → Mesh UV Projection
• Normal Map → direct material Normal routing; Normal / Tangent → approximate normal-texture candidates
• Bump → material Bump plus Bump Height, while preserving a chained Normal input
• Displacement → selected Octane Texture or Vertex Displacement; Vector Displacement → Octane Vertex Displacement
• RGB / Wavelength → Octane RGB Color
• Value → Octane Float Value
• Fresnel / Layer Weight → Octane Fresnel
• Vertex Color → Octane Color Vertex Attribute
• Attribute → Octane Attribute
• Ambient Occlusion → Octane Dirt Texture
• Object Info → compatible instance-color use; Camera Data → exact Octane Camera Data outputs

Color & Math (20 supported / 22 tracked)

• Math / Vector Math → Mapped to specific Add/Multiply/Math nodes based on inner operation
• Map Range → Octane Range
• Clamp → Octane Clamp
• Invert / Hue Saturation / Brightness Contrast / Gamma / RGB Curves → Octane Color Correction & Gamma nodes
• Blackbody → Black Body Emission; RGBToBW and ShaderToRGB use reported approximations
• Color Mix / MixRGB → native Composite Texture + two layers when available; legacy Mix fallback otherwise

Volumetrics (3 supported / 4 tracked)

• Volume Absorption → Octane Absorption Medium with Cycles density scaled by 100
• Volume Scatter → Octane Scattering Medium with Cycles density scaled by 100
• Direct Absorption + Scatter additions → one native Scattering Medium when compatible
• Linked density chains → Octane Multiply Texture scale stage; volume-only graphs → Null Material + Medium
• Volume Principled → best-effort Octane volume/standard-medium mapping

Passthrough & Logic (4 supported / 5 tracked)

• Node Groups / Group Input / Group Output — deeply traversed and rebuilt as converted groups without ungrouping
• Separate Color / RGB / XYZ — handled inline
• Combine Color / RGB / XYZ — handled inline

---

📁 Project Structure

Octanify/
├── README.md                            # User guide and architecture overview
├── LICENSE                              # GPL-3.0-or-later license
└── octanify/                            # Blender add-on package
    ├── __init__.py                      # Registration, bl_info, and scene properties
    ├── blender_manifest.toml            # Blender 4.2+ extension metadata
    ├── core/                            # Conversion backend
    │   ├── conversion_engine.py         # Transactional conversion orchestration and link rebuild
    │   ├── shader_detection.py          # Tree analysis, outputs, reroutes, and graph boundaries
    │   ├── graph_engine.py              # Cycle-safe dependency scheduling and node creation
    │   ├── shading_intent.py            # Destination-role tracing across paths and nested groups
    │   ├── geonodes_scan.py             # Recursive Geometry Nodes material discovery
    │   ├── node_registry.py             # 99 tracked Cycles node strategies and Octane candidates
    │   ├── property_mapper.py           # Values, enums, target-specific mappings, and fidelity-safe defaults
    │   ├── layout_engine.py             # Ranked layout, frame handling, graph spacing, and themes
    │   ├── gamma_system.py              # Intent-aware color/data gamma and texture duplication
    │   ├── light_converter.py           # Light power, Black Body emission, and gobo conversion
    │   ├── world_converter.py           # Flat/HDRI World environment conversion
    │   ├── volumetric_handler.py        # Cycles volume to Octane medium routing
    │   └── report.py                    # Structured statistics, warnings, and approximations
    ├── ui/                              # Blender interface layer
    │   ├── panel.py                     # Viewport and Shader Editor control-deck panels
    │   └── operators.py                 # Batch conversion, progress, cleanup, and material tools
    ├── utils/                           # Shared infrastructure
    │   ├── cache.py                     # Conversion and material deduplication cache
    │   └── logger.py                    # Structured console logging
    ├── NODE_SUPPORT.md                  # Cycles node support and fallback matrix
    ├── MATERIAL_FIDELITY.md             # Principled/Octane mapping and validation notes
    ├── docs/                            # Readiness evidence and OpenPBR mapping decisions
    ├── tests/                           # Repository-only automated regression tests
    │   ├── test_graph_and_registry.py   # Graph, mapping, lifecycle, and regression coverage
    │   ├── test_light_and_world_conversion.py # Lights, Worlds, gobos, and rollback coverage
    │   ├── test_deep_audit.py           # Cancellation, ownership and failure-path regressions
    │   └── test_panel_ui.py             # UI hierarchy and visibility regression coverage
    └── tools/                           # Repository-only Blender/Octane validation utilities
        ├── blender_fixture_scene.py     # Builds production-style validation materials
        ├── blender_validate_conversion.py # Runs integration and fidelity assertions
        ├── blender_validation_bootstrap.py # Loads the workspace add-on and Octane plugin
        ├── blender_probe_universal_material.py # Compares Universal Material initialization
        ├── blender_validate_phase4.py   # Composite layers and procedural-scale runtime checks
        ├── blender_validate_phase5.py   # Target selection, SSS, displacement, and volume checks
        ├── blender_validate_glossy_material.py # Glossy Material runtime checks
        ├── blender_validate_node_groups.py # Operator-level nested shader-group checks
        ├── blender_probe_bootstrap.py   # Bootstraps Octane material probes
        └── blender_inspect_octane_nodes.py # Inspects installed Octane node definitions

The clean release archive contains the license and runtime add-on files: LICENSE, __init__.py, blender_manifest.toml, core/, ui/, and utils/. Documentation, tests, validation tools, caches, and development metadata remain repository-only.

Additional repository tools cover transaction rollback, branch refresh, scene scope, animation, color policy, OpenPBR, and native audit regressions.

Validation

Validation includes Python regression tests, native graph/fault-injection matrices, foreground modal/synchronous parity, cancellation, scope/assignment handling, Undo/Redo, preview save/reopen, and matched texture-role renders. The latest audit checkpoint records 223 passing tests, eight native audit cases, the foreground matrix, and all 12 corrected finite-area HDR gates on Blender 5.2.2 / Octane 31.10. These are bounded workspace results, not universal renderer equivalence or certification of a previously distributed ZIP. Exact-install evidence and remaining release gates are tracked separately in the execution ledger.

Run Python checks from the repository root:

python -m unittest discover -s octanify/tests -p "test_*.py"
python -m compileall -q octanify/core octanify/ui octanify/utils octanify/tools octanify/tests

The root Python workflow runs unit, syntax, and deterministic packaging checks without Octane licensing. On a licensed local host, run the native validation runner with explicit Blender/Octane paths. Foreground validation uses a disposable factory-startup process:

cd octanify
$env:OCTANE_ADDON_ROOT = "$env:APPDATA\Blender Foundation\Blender\5.2\scripts\addons"
& 'C:\Program Files\Blender Foundation\Blender 5.2\blender.exe' --factory-startup --enable-event-simulate --python-exit-code 1 --python tools/blender_validate_foreground.py -- --json docs/production-readiness/runs/NEW-RUN/foreground.json

Check both the process exit code and JSON status; timer callback failures are recorded in JSON. The process closes itself. Keep historical evidence and choose a new run path. From the repository root, build a separate candidate with python octanify/tools/build_candidate.py --output-dir PATH; it includes the runtime allowlist and license with deterministic ZIP metadata and SHA-256, and excludes docs/tests/tools/caches. Current source verification does not certify an older archive. Do not replace a distributed archive until its exact installed copy has passed the candidate checks.

Headless conversion

The repository-only headless entry point enables Octane/Octanify before opening an optional input file, runs the normal conversion operator and its actual-plan preflight, and exports a JSON report. From the octanify/ package directory, with OCTANE_ADDON_ROOT configured:

& 'C:\Program Files\Blender Foundation\Blender 5.2\blender.exe' --background --factory-startup --python-exit-code 3 --python tools/blender_headless_convert.py -- --input PATH-TO-SCENE.blend --batch-mode ALL --json PATH-TO-REPORT.json

Exit 0 means clean conversion (or explicitly allowed degradation with --allow-degraded); 2 means degraded; 3 means failed/cancelled conversion or missing required capability. The tool exports a report, not a saved converted .blend file. Inspect skipped items too: a zero exit is not a promise that every scene item was converted.

⚠️ Current Support Limits

• Renderer fidelity: graph support does not imply pixel-identical output. Spot/Sun power/distribution, non-calibrated finite-light settings, unsupported HDRI transforms, and some material/procedural lobes remain approximate.
• Animation: reciprocal Mapping scale, weighted Universal/Glossy layer animation, NLA, and general light/World animation are not transferred. OpenPBR also reports unsupported linked SSS decomposition and dynamically clamped channels.
• Ownership and scope: collection-instance sources are not traversed. Isolation does not rewrite Geometry Nodes references or shared-mesh slots; linked/non-editable data is skipped. Mixed unowned native content can make refresh refuse safely.
• Release certification: broader glass/emission/bump/displacement/volume/gobo assets and artist approval, active-job disable/file-load/window-close fixtures, nested-group/many-light resource testing, hosted clean-checkout CI, and additional Blender/Octane versions and platforms remain open gates.

Use NODE_SUPPORT.md for node coverage, MATERIAL_FIDELITY.md for mapping boundaries, and the readiness ledger for current evidence. OpenPBR's mapping decisions and validation report explain why it remains experimental.

---

📥 Installation

Blender 4.2+

1. Download octanify.zip
2. Open Blender → Edit → Preferences → Add-ons
3. Click the dropdown arrow → Install from Disk
4. Select octanify.zip
5. Enable Octanify

Requirements

• Blender 4.2 or later
• OctaneRender plugin for Blender (required for Octane node creation)

Runtime-verified configuration and compatibility note

The current validated host is Windows, Blender 5.2.2 LTS and OctaneRender for Blender 31.10.0. Earlier evidence covers Blender 5.2.0 and 5.1. Blender 4.2 is the declared minimum, not proof that every 4.2+ combination or platform has passed; check the execution ledger and conversion report for the tested boundary.

On Blender 5.1+, Octanify supplies missing Octane output-state compatibility when needed without replacing a property already provided by the plugin.

Octane 31.9 may print an active_output_name callback traceback when Blender 5.1 activates a custom Octane World output. In validated conversions the property is still applied and Octane resolves the generated World output correctly. Treat it as a conversion failure only when the Octanify report also records a failed World conversion or the generated environment output is missing/unlinked.

---

🙏 Credits

• Architecture inspired by analysis of cycles2octane by Rodrigo Gama
• Ranked layout and crossing-reduction behavior is adapted for Octanify from node-arrange by Leonardo Pike-Excell

License

GPL-3.0-or-later — Compatible with Blender's licensing requirements.

---

_{Built with ☕ by Niloy Bhowmick}