RhiBlendSync v1.3.1

COMPLETE DOCUMENTATION

Operation • Installation • Tools • Configuration • SurfacePsycho

Architecture • Protocol • Data • Reliability • Troubleshooting

Guillaume Martin

[email protected]

Rhino 7-8 (Windows) • Rhino 8 (Mac) • Blender 4.0–5.1 • Bilingual FR/EN

TABLE OF CONTENTS

1. Overview

2. What's new — 1.2.4 → 1.3.1

3. Technical architecture

4. Installation

5. First launch and connection

6. Rhino commands

7. Rhino side panel

8. Blender interface

9. Synchronization modes

10. Geometry and mesh

11. SurfacePsycho integration

12. NURBS curves

13. Materials and shaders

14. Textures and UVs

15. Blocks and instances

16. Lights

17. Scene hierarchy

18. Push Blender → Rhino

19. Auto-sync reliability

20. Performance and optimizations

21. Configurable settings

22. Per-object settings

23. Network protocol

24. Troubleshooting

25. Technical specifications

1. OVERVIEW

RhiBlendSync is a bidirectional synchronization plugin between Rhinoceros 3D (Rhino 7 & 8) and Blender (4.0–5.1). It establishes a direct TCP connection between both applications to transfer in real time:

• Geometry: meshes with vertices, faces, normals and UVs
• Parametric surfaces: Rhino NURBS → SurfacePsycho parametric objects (STEP pipeline), SurfacePsycho patches → native Rhino NURBS
• NURBS curves: bidirectional, native curves included in the full sync
• Materials: colors, physical properties (glass, metal, emission), textures, per-face multi-materials
• Blocks: definitions and instances with position/rotation/scale and layer tracking
• Lights: point, spot, directional, rectangular (area) — with layer hierarchy
• Hierarchy: Rhino layers → Blender collections, followed live by every object type

The plugin consists of two parts:

• RhiBlendSync.rhp: compiled Rhino plugin in C# (.NET Framework 4.8 for Rhino 7/8 Windows, .NET 7.0 for Rhino 8 Mac). This is the TCP client that extracts data from the Rhino scene and sends it.
• Blender addon (__init__.py): Python addon. This is the TCP server that receives data and rebuilds the scene in Blender.

The interface is fully bilingual French/English with automatic system language detection.

Designed by Guillaume Martin — [email protected]

2. WHAT'S NEW — 1.2.4 → 1.3.1

The 1.2 refinement series (v1.2.4 → v1.2.27)

• Configurable TCP port on both sides: change the port in the Blender addon preferences and in RhiBSettings if 9876 conflicts with another tool. Both sides must match.
• Custom source name: give a Rhino file any source name via RhiBSettings. The alias is stored inside the .3dm itself (document strings), so it survives renaming, moving or copying the file — the link with the Blender source is never broken. Sources can also be renamed from Blender's Sources panel.
• Per-face multi-materials, full round trip: multi-material Breps keep per-face assignments Rhino → Blender; pushed multi-material objects return from Rhino as a single fused object with per-face data intact and your original Blender materials preferred by name.
• Push acknowledgment (push_ack): objects pushed from Blender are linked by ID; when they later come back from Rhino, RhiBlendSync updates the original Blender objects instead of duplicating them.
• Blender-origin marking: objects created in Blender are marked in Rhino and geometry-hashed; unmodified ones are excluded from the Rhino → Blender flows, killing re-sync loops for good.
• Absence-based cleanup: deletions propagate reliably — at the end of each sync, Blender removes only what truly no longer exists in Rhino (present-ID list), never your own Blender content.
• Area lights geometry & light change detection: rectangular light dimensions transfer correctly; lights modified in Rhino are detected by hash and re-synced without duplicating Blender-origin lights.
• v1.2.27 fixes: selection sync of a lone light, multi-material returns keeping Blender materials, protection of SurfacePsycho objects against mesh overwrites.

v1.3.1 — the parametric & reliability release

• SurfacePsycho integration, Rhino → Blender: NURBS surfaces, polysurfaces and extrusions are exported as STEP in real time and rebuilt by SurfacePsycho's own importer as true parametric patches — placed in the correct layer collection, tracked, updated and cleaned up without duplicates (see section 11).
• Per-object CAD control: two global toggles (full sync / selection sync) plus a per-object Mesh/SurfacePsycho override in the Rhino panel. Transitions mesh ↔ SP are handled cleanly in both directions.
• Auto-sync reliability overhaul: transactional delta (failed sends are replayed, nothing is ever lost), attribute-change detection (layer, name), automatic full sync after reconnection, hardened Blender server timer (see section 19).
• Complete layer hierarchy: meshes, native curves, lights, block instances and SurfacePsycho objects all follow Rhino layer changes in every sync mode — even layer-only moves. New lights are created directly in their layer collection.
• Native curves in the full sync: Rhino curves are now first-class citizens of the full synchronization (previously delta/selection only).
• Lightweight SP metadata (sp_meta): a layer or name change on a SurfacePsycho object transmits a tiny metadata message — no STEP re-export.
• SurfacePsycho node-group consolidation: automatic cleanup of duplicated SP node groups (caused by SP's own versioning on older .blend files), which also stops Blender's "Error registering node tool… duplicate(s)" console spam.
• UI: SurfacePsycho controls in the Rhino panel and settings dialog; SP object counter and "SurfacePsycho unavailable" indicator in the Blender N panel; per-object writes logged with object counts.

v1.3.1 — the mesh & polish release

• Mesh quality that works: meshing happens from the geometry with the requested parameters (the viewport render-mesh cache is no longer used). The initial grid is driven by amplification and a per-face floor, so density acts for real — from true low-poly to very dense — independently of surface spans/isocurves. Global, per-object and multi-material paths share the exact same parameters.
• Grid to the edges (new default): each face is meshed edge-to-edge like a standalone surface — clean quad grids, no triangulated border skirt. Free seams are exact on straight shared edges (extrusions); a watertight mode remains available in RhiBSettings for curved seams.
• Joined topology: O(n) hash welding with per-corner attributes — polysurface faces arrive connected and editable, while hard edges and UV seams stay exactly Rhino's.
• Native Blender shading: flat/smooth per face + Sharp marks on true creases, zero custom normals — Dissolve, Bevel and editing behave like on native meshes. Angle-welded extraction gives continuous smooth normals: SubD and fillets arrive clean; real SubD creases become legitimate Sharp edges.
• Mesh simplification (Blender addon preference, Planar by default): coplanar faces merged into ngons, face diagonals removed, border skirts paired into quads — curvature, creases, materials, seams and UVs preserved.
• Your Blender work survives: Shade Smooth / Auto Smooth / Flat choices are detected and re-applied through geometry re-syncs (persistent in the .blend); editing a block in Rhino updates definitions in place — modifiers, shading and manually added objects survive.
• Rhino 7 complete: dedicated Rh7 toolbar format (auto-staged, auto-shown on install), Newtonsoft.Json runtime shipped with the build (connection restored). Install the trio: .rhp + .dll + .rui together.
• Toolbar overhaul: official same-name RUI channel next to the .rhp (7/8, Win/Mac), guaranteed display via -ShowToolbar (McNeel RH-81206 workaround) deferred on the UI thread, plugin loads at Rhino startup, installer purges phantom registrations.
• Language: plugin follows Rhino's interface language; addon follows Blender's interface language (explicit choice beats system locale, English by default); full audit of hardcoded strings both sides; real version numbers everywhere (single-source bump).
• Automatic migration: meshes built by earlier versions are rebuilt once at the next sync (no stale custom-normal artifacts).

Known limitation: NURBS inside block definitions arrive as meshes (the parametric pipeline does not apply inside block definitions). Workaround: exploded block mode. Planned for a future release.

v1.3.1 — the mesh, platform & polish release

• Mesh quality that finally works: meshing is done from the geometry with your settings (the viewport render-mesh cache is no longer reused, which made the density slider inoperative). Rhino's standard mesher is the default; a per-object Detailed meshing option adds a curvature-driven grid for surfaces that deserve it.
• « Grid to edges » option: mesh each face like a standalone surface — a clean quad grid running edge to edge instead of a triangulated border skirt. Watertight is the default; free seams are ideal on straight-edged solids but leave unmatched vertices on curved shared edges.
• Native Blender shading: flat/smooth per face plus Sharp marks on true creases — zero custom normals. Dissolve, Bevel and every editing tool behave exactly as on native geometry.
• Continuous normals at patch borders: the extractor welds by angle after computing normals, so SubD and fillet seams arrive smooth while real creases (≥30°) stay sharp.
• Welded, editable topology: an O(n) hash weld joins duplicated Brep-face border vertices while normals and UVs are applied per corner — hard edges and texture seams stay exact. Degenerate faces produced by welding are now rejected (they could corrupt the mesh).
• Mesh simplification (Blender addon preference): Quads or Planar (ngons), off by default. It runs after the sync completes, one mesh at a time, and skips meshes above 80,000 vertices — see the warning in section 10.
• Your shading survives re-syncs: Shade Smooth / Auto Smooth / Flat applied in Blender persist through Rhino-side geometry updates.
• Block edits keep your work: when a block definition changes in Rhino (same sub-object count) it is updated in place — modifiers, shading and objects you added inside the definition survive.
• Toolbar on the official channel: the plugin loads at Rhino startup and ships its RUI next to the .rhp. Automatic display on Rhino 8 (Windows and Mac); on Rhino 7 the toolbar is loaded once manually (see section 4).
• Rhino 7 complete: dedicated Rh7-format RUI and Newtonsoft.Json.dll shipped with the build — the connection works.
• Language follows YOUR interface: the plugin follows Rhino's UI language, the addon follows Blender's. Network errors are described by RhiBlendSync itself instead of showing the operating system's localized text.
• Reliability: simplification never competes with reception (no more dropped connections on large scenes), send timeout raised to 120 s, and stale plug-in registrations are purged by the installer.

3. TECHNICAL ARCHITECTURE

Communication diagram

RHINO 7 / 8 Plugin C# (.rhp) TCP CLIENT

← JSON + zlib → TCP localhost:9876 (configurable)

BLENDER 4.0+ Addon Python TCP SERVER

Rhino-side components (.rhp)

Module	Role
RhiBlendSyncPlugin	Entry point. Loads components, registers panel, extracts RUI toolbar.
ConnectionManager	Manages the TCP connection to Blender (connect, disconnect, send, poll, handshake with source name).
SceneExtractor	Extracts geometry, materials, curves, blocks, lights and hierarchy from the Rhino scene.
SyncEngine	Orchestrates full sync (bulk & streaming), transactional delta sync, auto-sync, selection sync, SurfacePsycho STEP export and incoming push.
Protocol	JSON serialization, zlib compression, binary packing (4-byte header + payload).
Settings / ObjSettings	Global settings and per-object settings (Rhino UserDictionary, DL_* keys).
RhiBlendSyncPanel	Dockable Eto.Forms panel with per-object controls, including the SurfacePsycho group.
SettingsDialog	Configuration dialog (host, port, source name, quality, exports, SurfacePsycho toggles).
AllCommands	10 Rhino commands (RhiB*).
Localization (Loc)	FR/EN translation system.

Blender-side components (__init__.py)

Class	Role
RhiBlendSyncServer	TCP server listening on the configured port. Handles multiple connections; hardened timer processes messages progressively.
ClientHandler	Thread per connected Rhino client. Receives and queues messages.
SourceSceneManager	Manages the scene for one Rhino source (objects, curves, blocks, lights, SurfacePsycho objects, cleanup).
SourceMaterialManager	Creates and updates Blender materials (Principled BSDF, Glass, Metal, Emission, textures).
SourceCollectionManager	Manages the Blender collection hierarchy (by layers or by materials).
SourceBlockManager	Manages block definitions and instances (Collection Instances) with layer tracking.
SurfacePsycho bridge	Detects the SP add-on, pilots its STEP importer directly (synchronous), tracks SP objects by tags, consolidates node groups.
_Loc	FR/EN localization with Blender language detection.

4. INSTALLATION

4.0 What's in the download (v1.3.1)

Each Rhino version has its own archive, because the toolbar file format and the required runtime differ:

• Rhino 8 — Windows: RhiBlendSync.rhp + RhiBlendSync.rui (toolbar) + RhiBlendSync.pdb
• Rhino 7 — Windows: RhiBlendSync.rhp + RhiBlendSync.rui (Rhino 7 format) + Newtonsoft.Json.dll + RhiBlendSync.pdb
• Rhino 8 — Mac: RhiBlendSync.rhp (net7.0 build) + RhiBlendSync.rui
• Blender addon: a separate zip, identical on every platform

Keep the files together. Rhino loads a toolbar automatically when a .rui file sits next to the .rhp and carries the same name — that is the official plug-in toolbar channel. Extract the archive to a permanent folder and never move the .rhp alone. The .pdb only carries debug symbols (useful if you ever send a crash report); it is not required for the plugin to work.

4.0.1 Recommended installation (both methods keep the toolbar)

Before installing: remove the previous version. Close Rhino, then delete the old plugin file or folder. To find what Rhino actually loads, run _PlugInManager, select RhiBlendSync and read its File name — an old .rhp registered from another location will keep being loaded instead of the new one, whatever you copy elsewhere. The .bat installer (Windows) does this cleanup automatically, including stale registry registrations.

• Method A — Drag & drop: extract the archive to a folder you will keep, then drag RhiBlendSync.rhp onto the Rhino window. Rhino registers the plugin at that location, so the .rui next to it is found. Restart Rhino.
• Method B — Copy the folder contents: copy all extracted files into the Rhino plug-in folder shown below, then restart Rhino.

4.1 Rhino 8 (Windows)

Method A — Drag and drop (recommended): close Rhino, drag RhiBlendSync.rhp onto the Rhino window, accept, restart Rhino.

Method B — .bat installer: place RhiBlendSync.rhp and install_RhiBlendSync.bat in the same folder, close Rhino, double-click the .bat (it cleans old versions, copies the plugin and confirms), launch Rhino.

Method C — Manual copy: copy RhiBlendSync.rhp to:

%APPDATA%\McNeel\Rhinoceros\8.0\Plug-ins\RhiBlendSync (26c0600c-5e8f-4390-9b31-9a9db92e2ba4)\

IMPORTANT: the GUID in parentheses must match exactly 26c0600c-5e8f-4390-9b31-9a9db92e2ba4. Without this GUID, Rhino won't recognize the folder as a valid plugin folder.

4.2 Rhino 7 (Windows)

Rhino 7 — two specifics. (1) Install the whole archive: without Newtonsoft.Json.dll next to the .rhp the plugin loads but the connection fails silently (Rhino 8 provides that runtime, Rhino 7 does not). (2) The toolbar must be loaded once, manually: run the RhiBToolbar command after the first start, or use Tools → Toolbar Layout → Open and pick RhiBlendSync.rui. Rhino 7 then remembers it at every launch.

Same methods with the Rhino 7 build. Copy the trio together: RhiBlendSync.rhp + Newtonsoft.Json.dll + RhiBlendSync.rui (Rhino 7 does not bundle the JSON runtime, and uses its own toolbar format). Folder:

%APPDATA%\McNeel\Rhinoceros\7.0\Plug-ins\RhiBlendSync (26c0600c-5e8f-4390-9b31-9a9db92e2ba4)\

4.3 Rhino 8 (Mac)

Use install_RhiBlendSync_Mac.sh, or copy the net7.0 build of RhiBlendSync.rhp to:

/Applications/Rhino 8/Contents/Frameworks/RhCore.framework/Versions/A/Resources/ManagedPlugIns

Finder → Go → Go to Folder (Cmd+Shift+G), paste the path, create the folder if needed, restart Rhino.

4.4 Blender 4.0+ (all platforms)

• Edit → Preferences → Add-ons → Install
• Select the RhiBlendSync addon zip (or __init__.py) and enable « RhiBlendSync »
• The RhiBlendSync tab appears in the sidebar (N key)

Tested through Blender 5.1 (developed against 5.0.1). Compatible with Blender 4.0 and above. Optional: install the SurfacePsycho add-on to enable the parametric Rhino → Blender pipeline (section 11) — everything else works without it.

4.5 Upgrading from a previous version

• Install v1.3.1 on both sides (the handshake carries the version; matched versions are required for a healthy session).
• In Blender: remove/disable the old addon, restart Blender, install the new one, restart again. Verify the system console shows « [RhiBlendSync] Addon v1.3.1 charge ».
• In Rhino: replace the .rhp (methods above) and restart Rhino.

5. FIRST LAUNCH AND CONNECTION

5.1 What happens when Rhino loads

• Initializes core components (Settings, Connection, Extractor, SyncEngine)
• Registers the dockable side panel with icon (light/dark based on Rhino theme)
• Extracts the RUI toolbar from embedded resources and copies it to Rhino's UI folder
• Cleans parasitic version subfolders from old installations
• Opens the side panel and loads the toolbar automatically

A log file RhiBlendSync_log.txt is created on the Desktop if loading fails, with the complete execution trace for diagnostics.

5.2 Connection workflow

• In Blender: sidebar (N) → RhiBlendSync tab → Start. The TCP server starts on the configured port.
• In Rhino: Connect button (or RhiBConnect). A handshake exchanges the source name and plugin version.
• The connection is established; the source appears in Blender's Sources panel. You can now synchronize.

5.3 Source name

By default the source name is derived from the open .3dm file name. You can set a custom source name in RhiBSettings: the alias is stored inside the .3dm document itself, so it survives renaming, moving or copying the file — the link with the Blender source is never broken. Sources can also be renamed later from Blender's Sources panel.

6. RHINO COMMANDS

Command	Action	Detail
RhiBConnect	Connect	Connects to the Blender server on host:port (default 127.0.0.1:9876). Handshake with source name and version.
RhiBDisconnect	Disconnect	Stops auto-sync if active, then closes the TCP connection.
RhiBSync	Full Sync	Extracts and sends the entire scene: objects, materials, curves, blocks, lights, hierarchy, SurfacePsycho objects. Streaming in chunks of 50 objects on large scenes.
RhiBSyncSel	Sync Selection	Sends only selected objects: meshes, blocks, curves, lights — and NURBS as SurfacePsycho when the selection toggle or a per-object override says so.
RhiBAutoOn	Auto-sync ON	Starts continuous scene monitoring (default 500 ms interval). Events + attribute events + periodic scan; transactional delta syncs.
RhiBAutoOff	Auto-sync OFF	Stops continuous monitoring.
RhiBStatus	Status	Console report: connection status, tracked objects, instances, auto-sync state.
RhiBSettings	Settings	Opens the configuration dialog: host, port, source name, mesh quality, exports, SurfacePsycho toggles, auto-sync interval.
RhiBPanel	Panel	Opens the RhiBlendSync dockable side panel.
RhiBToolbar	Toolbar	Reloads the RhiBlendSync toolbar if it does not appear.

7. RHINO SIDE PANEL

The RhiBlendSync panel integrates as a native dockable panel. Sections:

Export section

• Export: include/exclude the selected object from synchronization
• Hierarchy: « By layers » or « By materials » (whole scene)
• Blocks: « Instances » or « Exploded » (global mode)

SurfacePsycho section (global)

• NURBS → SP (full sync): route eligible NURBS/polysurfaces/extrusions through the parametric pipeline during full syncs
• NURBS → SP (selection): same for selection syncs

These two checkboxes always reflect the true stored settings (they resynchronize on every selection change). Toggling either one while auto-sync runs triggers an automatic full sync so the whole scene converts by itself, in both directions, without duplicates.

Mesh Quality section

• Override: define a specific quality for this object
• Preset: Default / Very low (0.10) / Low (0.25) / Medium (0.50) / High (0.75) / Very high (0.95) / Custom
• Density: slider 0.01 – 1.00 (Custom mode)

Block section (visible for block instances)

• Override global setting + Mode: Instance or Exploded for this block only

SurfacePsycho section (per object — visible for NURBS/Brep/Extrusion)

• Override: this object ignores the global toggles
• Mode: Mesh or SurfacePsycho

Per-object writes are logged in the Rhino console with the number of objects touched (e.g. « Override SP ON → 3 objet(s) ») — multi-selection is supported. Changing a per-object SP override during auto-sync also triggers the automatic full sync.

Sync section & buttons

• Sync / Hash: last synchronization time and verification hash of the object
• Apply to selection: applies current panel settings to all selected objects
• Reset: resets the object settings to defaults

8. BLENDER INTERFACE

8.1 Main panel

Sidebar (N) → RhiBlendSync tab. Server status, connected client count, Start / Stop button, and the configurable port.

8.2 Rhino Sources panel

• Name: from the .3dm or the custom alias; can be renamed here
• Counters: Obj / Inst / Lum / SP (SurfacePsycho objects, new in v1.3)
• Indicator: « SurfacePsycho indisponible » with an error icon if SP objects were requested but the add-on is missing or disabled
• Progress: queue size during a heavy sync
• Actions: rename the source, delete the source (and all its Blender objects); global buttons: Delete all, Refresh

8.3 Push Blender → Rhino

« Send selection » button: sends selected meshes, curves and SurfacePsycho patches to Rhino. Visible when a source is connected.

8.4 Help panel

Version, main features and author contact. Collapsible.

9. SYNCHRONIZATION MODES

9.1 Full Sync

• Layer extraction (hierarchy), then materials (+ textures), then mesh objects, blocks, lights, native curves and SurfacePsycho objects
• JSON packaging, zlib compression; streaming in chunks of 50 objects with progress bars on both sides
• Ends with an absence-based cleanup: Blender removes only what no longer exists in Rhino (present-ID list, covering objects and lights)

9.2 Delta Sync (Auto-sync)

• Modified objects: RuntimeSerialNumber scan + instant object events
• Attribute changes: layer/name/material-by-attribute changes are caught by a dedicated Rhino event (v1.3) — invisible to serials and geometry events before
• Added / deleted: event-driven with scan backup
• Lights: geometric fingerprint + attribute detection
• SurfacePsycho: geometry change → STEP re-export; attribute-only change → lightweight sp_meta
• Settings changed: hash of global settings + per-object overrides (including SP); a change triggers an automatic full sync
• Transactional (v1.3): tracking commits only after a successful send; failed sends are replayed next tick (« Delta: rejeu de N changement(s) non transmis »)

9.3 Sync Selection

Extracts only selected objects: standard meshes, blocks (per their effective mode), curves, lights — and NURBS through the SurfacePsycho pipeline when enabled globally or per object.

9.4 Push Blender → Rhino

See section 18.

10. GEOMETRY AND MESH

• NURBS / Polysurfaces: meshed from geometry at the requested density (amplification-driven initial grid; v1.3.1) — unless routed through SurfacePsycho (section 11). Grid-to-edges topology by default; watertight mode optional
• Existing meshes: used directly
• Vertices / Faces: triangles and quads, Z-up on both sides, unit auto-conversion to meters
• Normals & UVs: per-face normals; per-vertex texture coordinates from Rhino's TextureCoordinates
• Blender rebuild: mesh.from_pydata() + batch foreach_set operations (50–100× faster on large scenes); weld/merge handled on the Rhino side for multi-material objects to keep per-face indices aligned

10.3 Mesh simplification — read this before enabling it

The Blender addon can simplify incoming meshes (addon preferences → Mesh simplification: None / Quads / Planar). It produces noticeably cleaner topology, but it is real geometry processing performed inside Blender:

• Default is None. Enable it deliberately, and re-sync fully for it to apply.
• Cost: on a large scene (several hundred objects) the simplification pass adds time and memory after the transfer — count on it running for a while on scenes of 500+ objects.
• Safety by design: it never runs during reception (the transfer keeps full speed), processes one mesh at a time so Blender stays responsive, and skips meshes above 80,000 vertices.
• Follow it: the Blender N panel shows a dedicated Simplification progress bar plus an overall one, and the system console names each mesh as it is processed.

Recommendation: leave simplification off for heavy production scenes, and turn it on for the models where topology matters (objects you will edit in Blender). It can also be enabled per project, since it is an addon preference.

11. SURFACEPSYCHO INTEGRATION

SurfacePsycho (by Romain Guimbal) brings parametric CAD surfaces to Blender. RhiBlendSync v1.3 integrates it natively in both directions.

11.1 Rhino → Blender (new in v1.3)

• Eligible geometry: NURBS surfaces, polysurfaces (Breps) and extrusions.
• Pipeline: the object is exported to STEP in an isolated headless document (original units preserved), transmitted over TCP, and rebuilt by SurfacePsycho's own importer, piloted directly and synchronously by RhiBlendSync.
• Result: true editable parametric patches — one SP object per face for polysurfaces (SurfacePsycho's data model), sharing the same Rhino ID.
• Placement: objects land in the Blender collection of their Rhino layer; unnamed objects are named SP_xxxxxxxx from their ID.
• Tracking: every SP object is tagged with its Rhino ID; repeated syncs never duplicate, geometry changes replace the previous import, deletions in Rhino clean up in Blender.
• Attribute-only changes: a layer or name change transmits a lightweight sp_meta message — no STEP re-export.
• Scale: the STEP interchange is normalized in millimeters; RhiBlendSync applies the constant conversion so documents in mm or meters both arrive at the correct size.

11.2 Choosing the pipeline

• Global toggles: « NURBS → SP (full sync) » and « NURBS → SP (selection) » in the panel and RhiBSettings (default: off → classic meshing).
• Per-object override: select a NURBS → SurfacePsycho group in the panel → Override + Mode (Mesh or SurfacePsycho).
• Transitions: switching a synced object mesh ↔ SP replaces the old representation cleanly, in both directions, with zero duplicates — and with auto-sync running, a toggle or override change triggers the conversion automatically.

11.3 Blender → Rhino

SurfacePsycho patches (Bezier & NURBS patches, multi-patch compounds, blend patches) are pushed to Rhino as native NURBS via SurfacePsycho's STEP exporter — control points, weights, knots and degrees preserved. SP objects in Blender are protected: a mesh coming back from Rhino never overwrites a live SP object.

11.4 Requirements, behavior without SP, limitation

• Requires the SurfacePsycho add-on enabled in Blender for the Rhino → Blender direction; everything else works without it.
• If SP is missing/disabled while SP sends are enabled: the console explains it and the Blender N panel shows « SurfacePsycho indisponible »; the rest of the sync proceeds normally.
• Node-group consolidation: on .blend files carrying node groups from an older SP version, SP's importer re-appends fresh copies at every import (« Error registering node tool … duplicate(s) » in the console). RhiBlendSync consolidates them automatically: same-version copies are merged, the newest version becomes canonical, old bases are set aside by renaming — existing SP objects keep working.
• Known limitation: NURBS inside block definitions arrive as meshes. Workaround: exploded block mode.

12. NURBS CURVES

• Rhino → Blender: native Rhino curves travel as editable NURBS curves — via selection sync, auto-sync, and (since v1.3) the full sync. They follow layer changes like every other object.
• Blender → Rhino: NURBS, Bezier and polyline curves are pushed as native Rhino NURBS. Control points, weights, degree, knots and closure preserved both ways.
• No collisions: curves created in Blender are marked; the native-curve flow never touches them (modified Blender curves return through their own dedicated flow that updates the originals).

13. MATERIALS AND SHADERS

Detected type	Blender shader	Detection / settings
Glass	ShaderNodeBsdfGlass	Transparency > 0.5 and « glass » hint. Color, Roughness, IOR.
Metal	ShaderNodeBsdfPrincipled	« metal » hint or Metallic > 0.5. Base Color, Metallic=1.0, Roughness, IOR.
Emission	ShaderNodeEmission	« emission » hint or non-black emission color. Color, Strength.
Standard	ShaderNodeBsdfPrincipled	All other cases. Base Color, Metallic, Roughness, Alpha, IOR, Emission Color/Strength, Normal.

• Assignment sources: ByObject, ByLayer, ByParent.
• Per-face multi-materials: multi-material Breps keep per-face assignments Rhino → Blender. Pushed multi-material objects return from Rhino as a single fused object with slots rebuilt in Rhino order, your original Blender materials preferred by name, and per-face indices applied exactly (welding is delegated to the Rhino side to keep faces/indices aligned).
• Principled BSDF input names use fallbacks for Blender 4.0+ compatibility.

14. TEXTURES AND UVS

• Extraction: image read from disk, encoded in base64, embedded in the material JSON (no shared folder needed)
• Hash cache: each texture is transmitted once per session; later syncs send only the hash (80–90% less data), with cache negotiation after Blender restarts and re-send on disk changes
• Reception: Blender decodes, saves to a temp file, loads via bpy.data.images.load()
• Node setup: ShaderNodeTexImage connected to the right input (Base Color, Metallic, Roughness, Normal, Emission) with Mapping + UV Texture Coordinate nodes; repeat/offset supported

15. BLOCKS AND INSTANCES

15.1 Instance mode (default)

• Definition → Collection: one Blender collection per block definition
• Instance → Empty with instance_type='COLLECTION' and the Rhino transform
• Smart updates: moving an instance updates only the transform; layer changes relink the instance to the right collection in every sync mode (v1.3)
• Memory: a block used 200 times is stored once

15.1.1 Editing a block definition in Blender (v1.3.1)

A Collection Instance shows geometry that lives somewhere else: in the collection holding the block definition. Since v1.3.1 those definitions are no longer hidden away — they are grouped in the Outliner under a collection named « · Block Definitions », and they are the geometry you edit when you want to change every instance at once.

• Where they are: in the Outliner, in the « Block Definitions » collection of the source. The definition objects sit at the world origin — that is normal: an instance is a copy of that geometry placed by its own transform.
• Why you do not see them in the viewport: the collection is excluded from the view layer (the unchecked box in the Outliner). The definitions are therefore invisible and not rendered, while remaining fully available — no duplicated geometry piled up at the origin.
• To edit a block: tick the collection checkbox in the Outliner to bring it into the view layer, edit the definition object (Edit Mode, modifiers, materials…), then untick it. Every instance in the scene updates instantly — that is the whole point of instancing.
• Your edits survive Rhino updates: when the block is modified in Rhino and the definition keeps the same number of sub-objects, RhiBlendSync updates the mesh data inside your existing objects instead of recreating them — modifiers, shading choices and objects you added to the definition are preserved (see section 2).
• Older .blend files made with a previous version are adopted automatically: their definitions move into this collection at the next sync.

15.2 Exploded mode

• Recursive decomposition with accumulated transforms and collision-free synthetic IDs at all nesting depths

15.3 Per-object override

Mode (instance/exploded) settable per block via the panel (keys DL_BlockOverride / DL_BlockMode). GetEffectiveBlockMode resolves the effective mode.

16. LIGHTS

Rhino	Blender	Transferred settings
Point light	POINT	Position, color, intensity
Spot light	SPOT	Position, direction, cone angle (hot spot), color, intensity
Directional	SUN	Direction, color, intensity
Rectangular	AREA	Position (re-centered), rectangle dimensions, direction (inverted normal), color, intensity

• Layer hierarchy (v1.3): the light's Rhino layer is transmitted; new lights are created directly inside their layer collection and follow later layer changes
• Attribute detection (v1.3): renaming a light or changing its layer is caught by the auto-sync even though the geometric fingerprint is unchanged
• Change detection: lights are fingerprinted; Blender-origin lights are compared by hash so Rhino edits return without duplication
• Rectangular conversion: center = Location + Length×0.5 + Width×0.5; direction = -normal (Blender emits along local -Z)

17. SCENE HIERARCHY

• By layers: each Rhino layer and sub-layer becomes a nested Blender collection
• By materials: objects grouped in collections named by material
• Live layer tracking (v1.3): meshes, curves, lights, block instances and SurfacePsycho objects follow Rhino layer changes in every mode — including layer-only moves with untouched geometry
• Hierarchy mode changes are detected by the settings hash and trigger an automatic full sync

18. PUSH BLENDER → RHINO

• Multi-selection: meshes, NURBS curves/surfaces and SurfacePsycho patches in one click, each routed to its original Rhino file via ID tracking
• GUID preservation: existing objects are replaced in place; new objects are created
• Push acknowledgment: Rhino replies with the ID mapping; Blender links the originals so later returns from Rhino update them instead of duplicating (a deterministic main ID is used for grouped pushes)
• Blender-origin marking: pushed objects are marked in Rhino with a geometry hash computed post-insertion; unmodified ones are excluded from Rhino → Blender flows (no loops), modified ones return through dedicated flows
• Materials & textures: Principled BSDF color/roughness/metallic + connected images travel to Rhino; multi-material objects keep per-face data
• Blender Collection Instances are converted to Rhino blocks

19. AUTO-SYNC RELIABILITY (V1.3)

• Transactional delta: serial/fingerprint tracking is committed only after a successful send. On failure, the changes go to a carry-over queue replayed at the next tick (« Delta: rejeu de N changement(s) non transmis »). A network hiccup can no longer silently lose a change.
• Attribute events: a dedicated Rhino event catches layer/name/attribute changes that neither geometry events nor serial scans can see.
• Automatic recovery: when the connection drops, reconnection attempts run in the background; on success, tracking is reset and a full sync fires automatically so the Blender scene rebuilds itself — including changes made during the outage.
• Hardened Blender timer: the server timer is wrapped so an unexpected error can never kill message processing; errors are logged and the server continues.

20. PERFORMANCE AND OPTIMIZATIONS

Optimization	Detail
Zlib compression	10–20× reduction; automatic detection on reception.
Texture hash cache	Each texture sent once per session; 80–90% less data on resyncs.
Chunked streaming	Full syncs stream in chunks of 50 objects with GC; 15,000+ objects handled.
Progressive loading	Blender processes objects per timer tick and stays responsive.
Batch mesh ops	foreach_get/foreach_set for UVs and face material indices: 50–100× faster.
Smart transactional delta	Only changes are re-sent; nothing is lost on failure.
Settings hash	Global settings + per-object overrides (incl. SurfacePsycho); a change triggers a full sync.
Lightweight SP meta	Layer/name changes on SP objects avoid STEP re-export.
Blender preservation	Custom UVs, Edit Mode changes and Blender materials are never overwritten.
Multi-source	Several Rhino clients simultaneously (one thread per client).
Auto cleanup	Absence-based deletion, stale-version purges on mode transitions, parasitic folders removal.

21. CONFIGURABLE SETTINGS

Setting	Default	Description
Host	127.0.0.1	Blender server address (LAN IP for two-machine setups)
Port	9876	TCP port — configurable on BOTH sides (Rhino RhiBSettings + Blender addon), must match
Source name	file name	Custom alias stored in the .3dm; survives rename/move/copy
Auto-sync interval	500 ms	Change detection frequency
Mesh quality	Medium (0.50)	Density for NURBS → mesh (drives the initial grid for real since v1.3.1)
Grid to edges	On	Faces meshed edge-to-edge, no border skirt (free seams); off = watertight (v1.3.1)
Mesh simplification	Planar	Blender addon preference: coplanar faces → ngons; Quads / None available (v1.3.1)
NURBS → SP (full sync)	Off	Route eligible NURBS through SurfacePsycho on full syncs
NURBS → SP (selection)	Off	Same for selection syncs
Export materials	Yes	Include materials
Export blocks	Yes	Include blocks/instances
Export lights	Yes	Include lights
Hierarchy	By layers	ByLayer or ByMaterial
Block mode	Instances	AsInstance or Exploded
Chunk size	50	Objects per chunk during full sync

22. PER-OBJECT SETTINGS

Stored in each Rhino object's UserDictionary, read automatically during extraction:

Key	Type	Description
DL_Export	bool	Include in sync (default: true)
DL_MeshOverride	bool	Override global mesh quality
DL_MeshDensity	double	Mesh density [0.01 – 1.00]
DL_MeshPreset	string	Name of selected preset
DL_BlockOverride	bool	Override global block mode
DL_BlockMode	string	« instance » or « exploded »
DL_SPOverride	bool	Override global SurfacePsycho toggles (v1.3)
DL_SPMode	string	« mesh » or « sp » (v1.3)
DL_LastSync	string	Last sync timestamp
DL_SyncHash	string	Verification hash

23. NETWORK PROTOCOL

23.1 Message format

[4 bytes: payload size, big-endian] [payload: JSON, zlib-compressed or raw]

Zlib detection is automatic on reception (magic byte 0x78). Maximum accepted size: 500 MB.

23.2 Message types

Type	Content / role
handshake	source_name, version, capabilities
full_sync	objects[], materials{}, layers[], block_definitions{}, block_instances[], lights[], curves[], present_ids[] (bulk mode)
sync_begin / chunk / sync_end	Streaming full sync; sync_end carries present_ids for the absence-based cleanup
partial_sync	Delta: objects[], curves[], removed_objects[], instance_transforms[], removed_instances[], lights[], materials{}
sp_import	SurfacePsycho payload: id, name, layer, hash, STEP data (base64) (v1.3)
sp_meta	Lightweight SP attribute update: id, name, layer (v1.3)
push_object / push_curve	Blender → Rhino payloads (mesh/curve/NURBS, material, textures, IDs)
push_ack	Rhino → Blender ID mapping after a push (original-object linking)

24. TROUBLESHOOTING

« Initialization failed » on startup

• Cause: two conflicting plugin folders (created by .rhi + manual copy)
• Solution: delete all RhiBlendSync/DirectLink folders in %APPDATA%\McNeel\Rhinoceros\8.0\Plug-ins\ then reinstall

No toolbar

• Solution: run RhiBToolbar; or delete .rui files containing DirectLink/RhiBlendSync in %APPDATA%\McNeel\Rhinoceros\8.0\UI\ and restart Rhino

Connect fails

• Blender is running and the RhiBlendSync server is started (Start button)
• The port matches on both sides and isn't blocked by a firewall or used by another addon (it is configurable if so)
• Host in RhiBSettings points to the Blender machine (127.0.0.1 locally)

« Error registering node tool … duplicate(s) » in the Blender console

• Cause: the .blend file contains SurfacePsycho node groups from an older SP version; SP's importer re-appends fresh copies at every import
• Solution: nothing to do — RhiBlendSync consolidates the duplicates automatically at the next SP sync (console: « SP: node groups consolides … »); the counter stops growing and existing SP objects keep working

« SurfacePsycho indisponible » in the Blender panel

• The SP toggles are enabled but the SurfacePsycho add-on is missing or disabled. Install/enable it, or turn the toggles off — the rest of the sync is unaffected

Auto-sync seems idle

• Check the Rhino console: « Delta non envoye … retente au prochain tick » means a transient send failure — the changes replay automatically
• After a Blender restart, the reconnection triggers a full sync by itself; if you disabled auto-reconnect, run RhiBConnect then RhiBSync

Meshes look faceted / cyan edges after updating from an older version

• Run one full sync (RhiBSync): meshes built by previous versions are migrated automatically to the native shading pipeline

Objects disappeared after a block mode change

• Switching instance ↔ exploded regenerates synthetic IDs; cleanup is automatic. If anything looks off, run a full sync

Toolbar missing

• Rhino 8: it appears automatically a few seconds after startup. If not, run RhiBToolbar — it reloads and shows it immediately, no restart needed
• Rhino 7: load it once manually (RhiBToolbar, or Tools → Toolbar Layout → Open → RhiBlendSync.rui). It is remembered afterwards
• In both cases, check that RhiBlendSync.rui sits next to RhiBlendSync.rhp — a .rhp moved alone loses its toolbar

Rhino 7: connection does nothing

• Cause: Newtonsoft.Json.dll missing next to the .rhp (Rhino 7 does not bundle it)
• Solution: reinstall the complete Rhino 7 archive — all files together

25. TECHNICAL SPECIFICATIONS

Element	Detail
Rhino plugin	Compiled C# (.rhp) — .NET Framework 4.8 (Windows Rh7/Rh8), .NET 7.0 (Mac Rh8)
Blender addon	Python (__init__.py) — all platforms
Protocol	TCP + JSON + zlib compression
Default port	9876 (configurable both sides)
Rhino required	Rhinoceros 7 or 8 (Windows 10/11), Rhinoceros 8 (macOS Sonoma+)
Blender required	Blender 4.0+ (tested through 5.1, developed against 5.0.1)
SurfacePsycho	Optional add-on — enables the parametric Rhino → Blender pipeline
Language	French / English (auto-detection)
Toolbar	RUI embedded in .rhp, automatic loading (RhiBToolbar as fallback)
Panel icons	Embedded (light and dark mode, 24x24)
Dependencies	None (Newtonsoft.Json bundled where Rhino doesn't provide it)
Plugin GUID	26c0600c-5e8f-4390-9b31-9a9db92e2ba4
Version	1.3.1
Author	Guillaume Martin
Contact	[email protected]

RhiBlendSync v1.3.1 Designed and developed by Guillaume Martin [email protected] © 2025–2026 Guillaume Martin. All rights reserved.