Surface Options

Surface options describe how an entity renders (colour, roughness, metalness, emission, textures). Genesis surfaces cannot be created before gs.init(), so SurfaceOptions records the specification in the config and creates the Genesis surface when the scene is built. Set one as an entity's surface field.

from eden.options.surfaces import PlasticSurfaceOptions

Surface appearance options (plastic, metal, glass, ...).

Attributes

SurfaceLike module-attribute

SurfaceLike: TypeAlias = SurfaceOptions | Surface

Either an Eden :class:SurfaceOptions (deferred) or a built Genesis :class:Surface.

Classes

SurfaceOptions

SurfaceOptions(**data)

Bases: ConfigurableOptions

Deferred, serializable description of a Genesis surface.

Genesis surfaces (gs.surfaces.*) cannot be instantiated before gs.init() (they reference gs.EPS internally), so they cannot be embedded directly in an EdenConfig that is constructed at import time. SurfaceOptions captures the surface specification as plain config data and materializes the real Genesis surface lazily via :meth:to_genesis_surface at build time.

Subclasses set _genesis_surface_cls to the corresponding gs.surfaces.* class; every non-None field (declared or extra) is forwarded to it.

PARAMETER	DESCRIPTION
color	Surface color. Shortcut for the primary texture with a single color (RGB or RGBA). TYPE: array - like[float] | None
opacity	Opacity of the surface in [0, 1]. TYPE: float | None
roughness	Roughness of the surface in [0, 1]. TYPE: float | None
metallic	Metalness of the surface in [0, 1]. TYPE: float | None
emissive	Emissive color of the surface. TYPE: array - like[float] | None
ior	Index of refraction. TYPE: float | None
vis_mode	How the entity should be visualized ('visual', 'collision', 'particle', 'sdf', 'recon'). TYPE: str | None
double_sided	Whether to render both sides of the surface. TYPE: bool | None
smooth	Whether to smooth face normals by interpolating vertex normals. Default True. TYPE: bool

Source code in eden/options/options.py

def __init__(self, **data):
    # Seed type metadata as construction data so BaseModel validates it into
    # __pydantic_extra__ (no-op for extra="forbid" classes, which use
    # the serialization envelope instead).
    data.update(option_metadata(self))
    # NOTE: all of the option modifications/validations should be done in the __init__ method
    try:
        BaseModel.__init__(self, **data)
    except ValidationError as exc:
        # A misspelled field on an extra="forbid" class should teach the field set, not just
        # name the typo. Only rewritten when every error is extra_forbidden.
        enriched = _enrich_extra_forbidden(type(self), exc)
        if enriched is None:
            raise
        raise enriched from None

Attributes

color class-attribute instance-attribute

color: FArrayType | None = None

opacity class-attribute instance-attribute

opacity: UnitInterval | None = None

roughness class-attribute instance-attribute

roughness: UnitInterval | None = None

metallic class-attribute instance-attribute

metallic: UnitInterval | None = None

emissive class-attribute instance-attribute

emissive: FArrayType | None = None

ior class-attribute instance-attribute

ior: float | None = None

vis_mode class-attribute instance-attribute

vis_mode: Literal['visual', 'collision', 'particle', 'sdf', 'recon'] | None = None

double_sided class-attribute instance-attribute

double_sided: bool | None = None

smooth class-attribute instance-attribute

smooth: bool = True

Methods:

to_genesis_surface

to_genesis_surface() -> Surface

Materialize the Genesis surface. Must be called after gs.init().

Source code in eden/options/surfaces.py

def to_genesis_surface(self) -> Surface:
    """Materialize the Genesis surface. Must be called after ``gs.init()``."""
    # Forward every set value (declared fields + dynamic extras), dropping unset
    # ``None`` shortcuts so the Genesis surface keeps its own defaults.
    kwargs = {key: value for key, value in self.dict().items() if value is not None}
    return self._genesis_surface_cls(**kwargs)

DefaultSurfaceOptions

DefaultSurfaceOptions(**data)

Bases: SurfaceOptions

Options for gs.surfaces.Default.

Source code in eden/options/options.py

def __init__(self, **data):
    # Seed type metadata as construction data so BaseModel validates it into
    # __pydantic_extra__ (no-op for extra="forbid" classes, which use
    # the serialization envelope instead).
    data.update(option_metadata(self))
    # NOTE: all of the option modifications/validations should be done in the __init__ method
    try:
        BaseModel.__init__(self, **data)
    except ValidationError as exc:
        # A misspelled field on an extra="forbid" class should teach the field set, not just
        # name the typo. Only rewritten when every error is extra_forbidden.
        enriched = _enrich_extra_forbidden(type(self), exc)
        if enriched is None:
            raise
        raise enriched from None

PlasticSurfaceOptions

PlasticSurfaceOptions(**data)

Bases: SurfaceOptions

Options for gs.surfaces.Plastic.

Source code in eden/options/options.py

def __init__(self, **data):
    # Seed type metadata as construction data so BaseModel validates it into
    # __pydantic_extra__ (no-op for extra="forbid" classes, which use
    # the serialization envelope instead).
    data.update(option_metadata(self))
    # NOTE: all of the option modifications/validations should be done in the __init__ method
    try:
        BaseModel.__init__(self, **data)
    except ValidationError as exc:
        # A misspelled field on an extra="forbid" class should teach the field set, not just
        # name the typo. Only rewritten when every error is extra_forbidden.
        enriched = _enrich_extra_forbidden(type(self), exc)
        if enriched is None:
            raise
        raise enriched from None

MetalSurfaceOptions

MetalSurfaceOptions(**data)

Bases: SurfaceOptions

Options for gs.surfaces.Metal.

Source code in eden/options/options.py

def __init__(self, **data):
    # Seed type metadata as construction data so BaseModel validates it into
    # __pydantic_extra__ (no-op for extra="forbid" classes, which use
    # the serialization envelope instead).
    data.update(option_metadata(self))
    # NOTE: all of the option modifications/validations should be done in the __init__ method
    try:
        BaseModel.__init__(self, **data)
    except ValidationError as exc:
        # A misspelled field on an extra="forbid" class should teach the field set, not just
        # name the typo. Only rewritten when every error is extra_forbidden.
        enriched = _enrich_extra_forbidden(type(self), exc)
        if enriched is None:
            raise
        raise enriched from None

BSDFSurfaceOptions

BSDFSurfaceOptions(**data)

Bases: SurfaceOptions

Options for gs.surfaces.BSDF — a general PBR surface (color / metallic / roughness).

Source code in eden/options/options.py

def __init__(self, **data):
    # Seed type metadata as construction data so BaseModel validates it into
    # __pydantic_extra__ (no-op for extra="forbid" classes, which use
    # the serialization envelope instead).
    data.update(option_metadata(self))
    # NOTE: all of the option modifications/validations should be done in the __init__ method
    try:
        BaseModel.__init__(self, **data)
    except ValidationError as exc:
        # A misspelled field on an extra="forbid" class should teach the field set, not just
        # name the typo. Only rewritten when every error is extra_forbidden.
        enriched = _enrich_extra_forbidden(type(self), exc)
        if enriched is None:
            raise
        raise enriched from None

GlassSurfaceOptions

GlassSurfaceOptions(**data)

Bases: SurfaceOptions

Options for gs.surfaces.Glass.

Source code in eden/options/options.py

def __init__(self, **data):
    # Seed type metadata as construction data so BaseModel validates it into
    # __pydantic_extra__ (no-op for extra="forbid" classes, which use
    # the serialization envelope instead).
    data.update(option_metadata(self))
    # NOTE: all of the option modifications/validations should be done in the __init__ method
    try:
        BaseModel.__init__(self, **data)
    except ValidationError as exc:
        # A misspelled field on an extra="forbid" class should teach the field set, not just
        # name the typo. Only rewritten when every error is extra_forbidden.
        enriched = _enrich_extra_forbidden(type(self), exc)
        if enriched is None:
            raise
        raise enriched from None

EmissionSurfaceOptions

EmissionSurfaceOptions(**data)

Bases: SurfaceOptions

Options for gs.surfaces.Emission.

Source code in eden/options/options.py

def __init__(self, **data):
    # Seed type metadata as construction data so BaseModel validates it into
    # __pydantic_extra__ (no-op for extra="forbid" classes, which use
    # the serialization envelope instead).
    data.update(option_metadata(self))
    # NOTE: all of the option modifications/validations should be done in the __init__ method
    try:
        BaseModel.__init__(self, **data)
    except ValidationError as exc:
        # A misspelled field on an extra="forbid" class should teach the field set, not just
        # name the typo. Only rewritten when every error is extra_forbidden.
        enriched = _enrich_extra_forbidden(type(self), exc)
        if enriched is None:
            raise
        raise enriched from None

Functions:

resolve_surface

resolve_surface(surface: SurfaceLike | None) -> Surface | None

Resolve a surface spec to a Genesis surface, building deferred SurfaceOptions.

Source code in eden/options/surfaces.py

def resolve_surface(surface: SurfaceLike | None) -> Surface | None:
    """Resolve a surface spec to a Genesis surface, building deferred ``SurfaceOptions``."""
    if isinstance(surface, SurfaceOptions):
        return surface.to_genesis_surface()
    return surface

See also

• Sensors and rendering guide