sverchok-syntax-sockets
Use when connecting Sverchok nodes, debugging socket compatibility errors, or choosing the right socket type. Prevents the common mistake of connecting incompatible socket types without understanding implicit conversions. Covers all 16 socket types (vertices, strings, matrices, curves, surfaces, fields), socket properties, and type conversion rules. Keywords: socket type, SvVerticesSocket, SvStringsSocket, SvMatrixSocket, socket conversion, compatible sockets, data processing flags, Sverchok sockets, connect different types, socket color meaning.
- License 许可
- MIT
- 最近更新
- 2026-11-09
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- sverchok-syntax-sockets
- license
- MIT
- metadata
- { "author": "OpenAEC-Foundation", "version": "1.0" }
- description
- Use when connecting Sverchok nodes, debugging socket compatibility errors, or choosing the right socket type. Prevents the common mistake of connecting incompatible socket types without understanding implicit conversions. Covers all 16 socket types (vertices, strings, matrices, curves, surfaces, fields), socket properties, and type conversion rules. Keywords: socket type, SvVerticesSocket, SvStringsSocket, SvMatrixSocket, socket conversion, compatible sockets, data processing flags, Sverchok sockets, connect different types, socket color meaning.
- compatibility
- Designed for Claude Code. Requires Blender 4.0+/5.x with Sverchok v1.4.0+.
02 资源文件 3
- 参考文档references/anti-patterns.md10.2 KB
- 参考文档references/examples.md10.3 KB
- 参考文档references/methods.md14.1 KB
03 SKILL.md 正文
sverchok-syntax-sockets
Quick Reference
All 16 Socket Types
| Socket Class | Color (RGBA) | Data Type | nesting_level |
SNLite |
|---|---|---|---|---|
SvStringsSocket |
(0.6, 1.0, 0.6, 1.0) |
int, float, generic lists | 2 | s |
SvVerticesSocket |
(0.9, 0.6, 0.2, 1.0) |
3D coordinates (x,y,z) |
3 | v |
SvMatrixSocket |
(0.2, 0.8, 0.8, 1.0) |
4x4 mathutils.Matrix |
1 | m |
SvQuaternionSocket |
(0.9, 0.4, 0.7, 1.0) |
mathutils.Quaternion |
2 | — |
SvColorSocket |
(0.9, 0.8, 0.0, 1.0) |
RGBA tuples (r,g,b,a) |
3 | — |
SvCurveSocket |
(0.5, 0.6, 1.0, 1.0) |
SvCurve instances |
2 | C |
SvSurfaceSocket |
(0.4, 0.2, 1.0, 1.0) |
SvSurface instances |
2 | S |
SvSolidSocket |
(0.0, 0.65, 0.3, 1.0) |
Part.Shape (FreeCAD) |
2 | So |
SvScalarFieldSocket |
(0.9, 0.4, 0.1, 1.0) |
SvScalarField instances |
2 | SF |
SvVectorFieldSocket |
(0.1, 0.1, 0.9, 1.0) |
SvVectorField instances |
2 | VF |
SvDictionarySocket |
(1.0, 1.0, 1.0, 1.0) |
Python dict objects |
2 | D |
SvObjectSocket |
(0.69, 0.74, 0.73, 1.0) |
Blender bpy.types.Object |
2 | o |
SvFilePathSocket |
(0.9, 0.9, 0.3, 1.0) |
File path strings | 2 | FP |
SvTextSocket |
(0.68, 0.85, 0.90, 1.0) |
Text strings | 2 | — |
SvDummySocket |
(0.8, 0.8, 0.8, 0.3) |
Type placeholder only | 2 | — |
SvChameleonSocket |
dynamic | Adopts linked socket type | dynamic | — |
Critical Warnings
NEVER connect mismatched socket types without understanding the implicit conversion policy — silent data transformations can corrupt geometry.
NEVER use SvStringsSocket for structured geometry objects (curves, surfaces, fields) — the data will pass through but lose type safety and trigger silent conversion failures downstream.
ALWAYS use sv_get(default=[[]]) with a default value on input sockets to avoid SvNoDataError when the socket is unconnected.
ALWAYS call sv_forget() before replace_socket() to clear stale cached data — the old socket_id becomes invalid after replacement.
NEVER read socket.other on an output socket with multiple connections — it returns one arbitrary linked socket, not all of them.
Decision Trees
Choosing the Right Socket Type
What data do you need to transport?
Numbers, booleans, or generic Python objects?
└── SvStringsSocket (green)
3D point coordinates?
└── SvVerticesSocket (orange)
4x4 transformation matrix?
└── SvMatrixSocket (teal)
Rotation only (no translation/scale)?
└── SvQuaternionSocket (pink)
RGBA color values?
└── SvColorSocket (yellow)
Parametric curve object (maps t -> point)?
└── SvCurveSocket (blue)
Parametric surface object (maps u,v -> point)?
└── SvSurfaceSocket (deep purple)
CAD solid (requires FreeCAD/OpenCascade)?
└── SvSolidSocket (green)
Scalar field (maps R³ -> R)?
└── SvScalarFieldSocket (dark orange)
Vector field (maps R³ -> R³)?
└── SvVectorFieldSocket (deep blue)
Python dict / key-value data?
└── SvDictionarySocket (white)
Blender scene object reference?
└── SvObjectSocket (grey-green)
File system path?
└── SvFilePathSocket (yellow-green)
Raw text string?
└── SvTextSocket (light blue)
Placeholder for dynamic socket (not yet typed)?
└── SvDummySocket (grey, semi-transparent)
Socket that should mirror the connected socket type?
└── SvChameleonSocket (dynamic color)
Debugging Socket Compatibility Errors
Connection refused or TypeError on sv_get?
Are socket colors the same?
├── Yes → socket types match, error is in data structure
└── No → implicit conversion will be attempted
Check the to_socket's default_conversion_name:
├── 'DefaultImplicitConversionPolicy'
│ └── See DefaultImplicitConversionPolicy conversion table
├── 'FieldImplicitConversionPolicy'
│ └── Matrices/vertices/strings auto-convert to fields
├── 'LenientImplicitConversionPolicy'
│ └── Any data passes through unchanged
├── 'SolidImplicitConversionPolicy'
│ └── Attempts to_solid_recursive(); raises on failure
└── None / no policy
└── Connection is blocked — ImplicitConversionProhibited raised
Is from_socket a lenient type?
├── SvStringsSocket, SvObjectSocket, SvColorSocket, SvVerticesSocket → YES, data passes
└── Otherwise → conversion policy decides
Essential Patterns
Pattern 1: Read and Write Socket Data in process()
# Sverchok v1.4.0+: inside a custom node's process() method
def process(self):
# Read input — ALWAYS provide default to handle unconnected socket
verts_in = self.inputs['Vertices'].sv_get(default=[[]])
# deepcopy=False safe ONLY if you will NOT mutate the list
numbers_in = self.inputs['Count'].sv_get(default=[[1]], deepcopy=False)
# ... compute result ...
# Write output — data MUST match nesting_level of socket
# SvVerticesSocket nesting_level=3: [[(x,y,z), ...], ...]
self.outputs['Vertices'].sv_set([[(0.0, 0.0, 0.0)]])
# SvStringsSocket nesting_level=2: [[val, val, ...], ...]
self.outputs['Count'].sv_set([[1, 2, 3]])
# SvMatrixSocket nesting_level=1: [Matrix, Matrix, ...]
import mathutils
self.outputs['Matrix'].sv_set([mathutils.Matrix.Identity(4)])
Pattern 2: Replace a Socket Type at Runtime
# Sverchok v1.4.0+: inside sv_update() or sv_init()
def sv_update(self):
# ALWAYS call sv_forget() before replace_socket()
old_socket = self.inputs.get('Data')
if old_socket is not None:
old_socket.sv_forget()
new_socket = old_socket.replace_socket('SvCurveSocket', 'Curve')
# new_socket is the replacement; old_socket reference is now invalid
Pattern 3: Access socket_id and other
# Sverchok v1.4.0+
import bpy
tree = bpy.data.node_groups["MyTree"]
node = tree.nodes["MyNode"]
sock = node.inputs['Vertices']
# socket_id: unique string key for the data cache
cache_key = sock.socket_id
# Returns: str (hash of node_id + identifier + direction)
# other: the socket on the far end of the link
if sock.is_linked:
upstream = sock.other
# For INPUT sockets: returns the single connected output socket
# For OUTPUT sockets: returns ONE of the connected input sockets (arbitrary)
print(upstream.node.name, upstream.name)
Pattern 4: Set Socket Processing Flags
# Sverchok v1.4.0+: define allowed flags in sv_init()
def sv_init(self, context):
sock = self.inputs.new('SvVerticesSocket', 'Vertices')
# Enable which processing flags the user can toggle in the UI
sock.allow_flatten = True
sock.allow_graft = True
sock.allow_wrap = True
sock.allow_unwrap = True
sock.allow_simplify = True
# The actual use_* flags are set by the user in the socket UI
# Processing flag *behavior* is handled by the sv_get() pipeline
# See: sverchok-syntax-data for how flags transform data
Pattern 5: Implicit Conversion: Field Sockets
# Sverchok v1.4.0+: SvScalarFieldSocket and SvVectorFieldSocket
# use FieldImplicitConversionPolicy automatically
# When a SvStringsSocket (numbers) is connected to SvScalarFieldSocket:
# → numbers are wrapped in SvConstantScalarField automatically
# When a SvVerticesSocket is connected to SvVectorFieldSocket:
# → vectors are wrapped in SvConstantVectorField automatically
# When a SvMatrixSocket is connected to SvVectorFieldSocket:
# → matrix creates SvMatrixVectorField automatically
# This means: nodes producing numbers/vectors can feed field-consuming nodes
# without explicit conversion nodes in the node tree.
# Reading field data in process():
def process(self):
from sverchok.utils.field.scalar import SvScalarField
fields = self.inputs['Field'].sv_get()
# fields is [[SvScalarField, ...], ...]
for field in fields[0]:
point_value = field.evaluate(0.0, 0.0, 0.0) # Returns float
Socket Properties Reference
SvSocketCommon Properties
| Property | Type | Default | Purpose |
|---|---|---|---|
color |
tuple |
class-defined | RGBA display color in node editor |
label |
StringProperty |
'' |
Override display name in UI |
use_prop |
BoolProperty |
False |
Show embedded property widget |
prop_name |
StringProperty |
'' |
Node attribute to display as property |
objects_number |
IntProperty |
0 |
Count of data objects (informational) |
is_mandatory |
BoolProperty |
False |
Block node execution if unconnected |
nesting_level |
IntProperty |
2 |
Expected list nesting depth |
default_mode |
EnumProperty |
'EMPTY_LIST' |
Fallback when no data: NONE / EMPTY_LIST / MATRIX / MASK |
pre_processing |
EnumProperty |
'NONE' |
Pre-processing: NONE / ONE_ITEM |
quick_link_to_node |
str |
class-defined | Node bl_idname shown in quick-link button |
default_conversion_name |
str |
class-defined | Conversion policy class name |
SvSocketProcessing Flags
| Flag Property | Enable Property | Default | Effect |
|---|---|---|---|
allow_flatten |
use_flatten |
False |
Flattens nested list to single level |
allow_flatten_topology |
use_flatten_topology |
False |
Flattens preserving topology structure |
allow_simplify |
use_simplify |
False |
Removes redundant outer nesting |
allow_graft |
use_graft |
False |
Adds a nesting level |
allow_unwrap |
use_unwrap |
False |
Removes one nesting level |
allow_wrap |
use_wrap |
False |
Adds one nesting level |
Note: allow_* properties control whether the flag is visible in the UI. use_* properties are the actual state set by the user. Processing flag behavior (how data is transformed) is documented in sverchok-syntax-data.
quick_link_to_node Values
| Socket | quick_link_to_node |
|---|---|
SvMatrixSocket |
'SvMatrixInNodeMK4' |
SvVerticesSocket |
'GenVectorsNode' |
SvFilePathSocket |
'SvFilePathNode' |
SvDictionarySocket |
'SvDictionaryIn' |
SvScalarFieldSocket |
'SvNumberNode' |
SvVectorFieldSocket |
'GenVectorsNode' |
SvLoopControlSocket |
'SvLoopInNode' |
Implicit Conversion Policies
DefaultImplicitConversionPolicy: Explicit Conversions
| From | To | Conversion Applied |
|---|---|---|
SvVerticesSocket |
SvMatrixSocket |
Creates translation matrices from vertices |
SvVerticesSocket |
SvColorSocket |
Appends alpha=1.0: (x,y,z) → (x,y,z,1) |
SvMatrixSocket |
SvVerticesSocket |
Extracts translation column |
SvMatrixSocket |
SvQuaternionSocket |
mat.to_quaternion() |
SvQuaternionSocket |
SvMatrixSocket |
quat.to_matrix().to_4x4() |
SvStringsSocket |
SvVerticesSocket |
Number v → vector (v, 0, 0) |
SvStringsSocket |
SvColorSocket |
Number v → color (v, v, v, 1) |
Lenient socket types accept data from any socket without conversion:
lenient_socket_types = {
'SvStringsSocket', 'SvObjectSocket', 'SvColorSocket', 'SvVerticesSocket',
}
FieldImplicitConversionPolicy: Additional Field Conversions
Used by SvScalarFieldSocket and SvVectorFieldSocket.
| From | To | Conversion Applied |
|---|---|---|
SvStringsSocket |
SvScalarFieldSocket |
Numbers → SvConstantScalarField |
SvVerticesSocket |
SvVectorFieldSocket |
Vertices → SvConstantVectorField |
SvMatrixSocket |
SvVectorFieldSocket |
Matrix → SvMatrixVectorField |
Falls through to DefaultImplicitConversionPolicy for all other type pairs.
Policy Assignment Per Socket
# Sverchok v1.4.0+: source: core/sockets.py
class SvVerticesSocket:
default_conversion_name = ConversionPolicies.DEFAULT.conversion_name
# → 'DefaultImplicitConversionPolicy'
class SvScalarFieldSocket:
default_conversion_name = ConversionPolicies.FIELD.conversion_name
# → 'FieldImplicitConversionPolicy'
class SvVectorFieldSocket:
default_conversion_name = ConversionPolicies.FIELD.conversion_name
# → 'FieldImplicitConversionPolicy'
class SvTextSocket:
default_conversion_name = ConversionPolicies.LENIENT.conversion_name
# → 'LenientImplicitConversionPolicy'
class SvSolidSocket:
default_conversion_name = ConversionPolicies.SOLID.conversion_name
# → 'SolidImplicitConversionPolicy'
Advanced Data Types
SvCurve
Abstract base class from sverchok/utils/curve/__init__.py. Maps parameter t ∈ [t_min, t_max] to a 3D point. Not necessarily arc-length parametrized.
curve.get_u_bounds()→(t_min, t_max)curve.evaluate(t)→numpy.ndarrayshape(3,)curve.evaluate_array(ts)→numpy.ndarrayshape(N, 3)
SvSurface
Abstract base class from sverchok/utils/surface/__init__.py. Maps (u, v) to 3D points.
surface.get_u_min(), surface.get_u_max()surface.get_v_min(), surface.get_v_max()surface.evaluate(u, v)→numpy.ndarrayshape(3,)surface.evaluate_array(us, vs)→numpy.ndarrayshape(N, 3)
SvScalarField
From sverchok/utils/field/scalar.py. Maps R³ → R.
field.evaluate(x, y, z)→floatfield.evaluate_grid(xs, ys, zs)→numpy.ndarray- Supports: addition, multiplication, composition, gradient
SvVectorField
From sverchok/utils/field/vector.py. Maps R³ → R³.
field.evaluate(x, y, z)→tuple(dx, dy, dz)field.evaluate_grid(xs, ys, zs)→ threenumpy.ndarray(dxs, dys, dzs)- Two interpretations: relative (P + field(P)) or absolute (field(P))
Part.Shape (Solids)
FreeCAD/OpenCascade BRep objects. Requires FreeCAD installed alongside Blender. Transported by SvSolidSocket. SolidImplicitConversionPolicy attempts to_solid_recursive() on connected data.
dict (Dictionaries)
Python dict objects in SvDictionarySocket. Use unzip_dict_recursive(data) from sverchok.utils.dictionary to convert nested list-of-dicts to dict-of-nested-lists.
Reference Links
- references/methods.md — Complete API signatures: SvSocketCommon, SvSocketProcessing, ConversionPolicies, replace_socket, socket_id, other
- references/examples.md — Working code examples: custom socket types, field conversions, dynamic socket replacement
- references/anti-patterns.md — What NOT to do with sockets, with WHY explanations
Official Sources
04 同仓库更多 Skills
manimce-best-practices
Trigger when: (1) User mentions "manim" or "Manim Community" or "ManimCE", (2) Code contains `from manim import *`, (3) User runs `manim` CLI commands, (4) Working with Scene, MathTex, Create(), or ManimCE-specific classes. Best practices for Manim Community Edition - the community-maintained Python animation engine. Covers Scene structure, animations, LaTeX/MathTex, 3D with ThreeDScene, camera control, styling, and CLI usage. NOT for ManimGL/3b1b version (which uses `manimlib` imports and `manimgl` CLI).
drawio
Create, edit, replicate, import, and export draw.io diagrams with an offline YAML-first workflow: architecture, network topologies, flowcharts, UML/ER, org charts, Mermaid/CSV conversion, existing .drawio bundles, style presets, themes, and non-publication formula diagrams. For publication figures (paper, thesis, IEEE, camera-ready) use drawio-academic-skills instead.
drawio-academic-skills
Publication-figure overlay for draw.io. Use instead of drawio whenever the diagram is for a paper, thesis, dissertation, journal, conference, IEEE/ACM submission, manuscript, camera-ready, Word/LaTeX figure, or other publication. Applies venue, figure-type, color, caption/legend, formula, and paper-readability gates for architecture, workflow, roadmap, network-topology, and replicated paper figures.
uncertainty-and-units
Tracks physical units and propagates measurement uncertainty in scientific calculations using pint and uncertainties. Use for unit conversion and dimensional checking, GUM uncertainty budgets, Type A and Type B evaluation, coverage factors and expanded uncertainty, Monte Carlo propagation, significant-figure and plus-minus reporting, error propagation through curve fits, CODATA constants, auditing Python code for stripped units or broken uncertainty propagation, and order-of-magnitude plausibility checks using dimensionless groups (Reynolds, Peclet, Damkohler, Knudsen, Biot, Womersley), characteristic scales such as diffusion time or Debye length, and observed magnitude ranges. Trigger on "is this number physically reasonable", "sanity check these units", "what regime is this flow in", or a result that looks off by orders of magnitude.
statistical-analysis
Guided statistical analysis for research data - test selection, assumption checking, effect sizes, power analysis, Bayesian alternatives, and APA-formatted reporting. Use whenever a user wants to compare groups, test a hypothesis, analyze experimental or survey data, check statistical assumptions, compute required sample sizes, or write up results - even if they never name a specific test. Covers t-tests, ANOVA, chi-square, correlation, regression, non-parametric and Bayesian methods. For low-level model APIs, see the statsmodels and pymc skills.
simpy
Builds, inspects, tests, and analyzes bounded process-based discrete-event simulations with SimPy. Use for event scheduling, resource queues, interrupts, monitoring, independent replications, warm-up, and reproducible output analysis.