Sverchok Syntax Sockets

sverchok-syntax-sockets

Quick Reference

All 16 Socket Types

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

SvSocketProcessing Flags

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

Implicit Conversion Policies

DefaultImplicitConversionPolicy: Explicit Conversions

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.

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.ndarray shape (3,)
• curve.evaluate_array(ts) → numpy.ndarray shape (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.ndarray shape (3,)
• surface.evaluate_array(us, vs) → numpy.ndarray shape (N, 3)

SvScalarField

From sverchok/utils/field/scalar.py. Maps R³ → R.

• field.evaluate(x, y, z) → float
• field.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) → three numpy.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

• https://github.com/nortikin/sverchok/blob/master/core/sockets.py
• https://github.com/nortikin/sverchok/blob/master/core/socket_conversions.py
• https://github.com/nortikin/sverchok/blob/master/core/socket_data.py