Node Types

This section documents all the different node types available in s3dgraphy.

Stratigraphic Nodes

class s3dgraphy.nodes.stratigraphic_node.StratigraphicNode(node_id, name, description='')

Bases: Node

Base class for all stratigraphic units within the graph structure. Inherits from Node and provides additional functionality specific to stratigraphy.

node_type = 'StratigraphicNode'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.StratigraphicUnit(node_id, name, description='')

Bases: StratigraphicNode

node_type = 'US'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.StructuralVirtualStratigraphicUnit(node_id, name, description='')

Bases: StratigraphicNode

node_type = 'USVs'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.SeriesOfStratigraphicUnit(node_id, name, description='')

Bases: StratigraphicNode

node_type = 'serSU'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.SeriesOfNonStructuralVirtualStratigraphicUnit(node_id, name, description='')

Bases: StratigraphicNode

node_type = 'serUSVn'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.SeriesOfStructuralVirtualStratigraphicUnit(node_id, name, description='')

Bases: StratigraphicNode

node_type = 'serUSVs'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.SeriesOfDocumentaryStratigraphicUnit(node_id, name, description='')

Bases: StratigraphicNode

node_type = 'serUSD'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.NonStructuralVirtualStratigraphicUnit(node_id, name, description='')

Bases: StratigraphicNode

node_type = 'USVn'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.SpecialFindUnit(node_id, name, description='')

Bases: StratigraphicNode

node_type = 'SF'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.VirtualSpecialFindUnit(node_id, name, description='')

Bases: StratigraphicNode

node_type = 'VSF'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.ReusedSpecialFind(node_id, name, description='')

Bases: StratigraphicNode

Reused Special Find (RSF) — re-used architectural / decorative element (spolia) in archaeological reconstructions.

Typological cousin of SpecialFindUnit (SF) and VirtualSpecialFindUnit (VSF): all three render as octagons. RSF is distinguished by its red border (#9B3333) and a white fill, marking the element as physically present and re-deployed out of its original construction context.

Originating Development Project: DP-26 (spolia project, last DP before the EM 1.5 cut). Visual stencil shipped in the palette template at templates/em_palette_template.graphml.

node_type = 'RSF'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.DocumentaryStratigraphicUnit(node_id, name, description='')

Bases: StratigraphicNode

node_type = 'USD'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.TransformationStratigraphicUnit(node_id, name, description='')

Bases: StratigraphicNode

node_type = 'TSU'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.WorkingUnit(node_id, name, description='')

Bases: StratigraphicNode

node_type = 'UL'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.NegativeStratigraphicUnit(node_id, name, description='')

Bases: StratigraphicNode

Negative Stratigraphic Unit (US negativa / USN).

Describes a lacuna, a removal, or an interface that marks the absence of matter rather than its presence — e.g. a pit cut, an erosion surface, a demolition void. Distinct from a plain StratigraphicUnit (which is positive by default), but equally observable on the ground: it is a real stratigraphic element, hence classified in the real family alongside StratigraphicUnit and DocumentaryStratigraphicUnit.

node_type = 'USN'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.ContinuityNode(node_id, name, description='')

Bases: StratigraphicNode

node_type = 'BR'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.StratigraphicEventNode(node_id, name, description='')

Bases: StratigraphicNode

node_type = 'SE'

__init__(node_id, name, description='')

class s3dgraphy.nodes.stratigraphic_node.UnknownNode(node_id, name, description='')

Bases: StratigraphicNode

node_type = 'unknown'

__init__(node_id, name, description='')

Paradata Nodes

class s3dgraphy.nodes.paradata_node.ParadataNode(node_id, name, description='', url=None)

Bases: Node

Classe base per i nodi che rappresentano metadati o informazioni su come i dati sono stati generati.

url

URL associato al nodo.

Type:

str

node_type = 'ParadataNode'

__init__(node_id, name, description='', url=None)

Representation Nodes

class s3dgraphy.nodes.representation_node.RepresentationNode(node_id: str, name: str, type: str = 'generic', transform: Dict[str, List[str]] | None = None, description: str = '')

Bases: Node

Base class for all representation nodes in 3D space.

This class provides common functionality for RepresentationModelNode, RepresentationModelDocNode, and RepresentationModelSpecialFindNode.

node_type

Type of node, set by child classes

Type:

str

type

The type of representation (e.g. “RM”, “spatialized_image”, “generic”)

Type:

str

transform

Transformation data for positioning in 3D space

Type:

dict

node_type = 'representation_node'

__init__(node_id: str, name: str, type: str = 'generic', transform: Dict[str, List[str]] | None = None, description: str = '')

Initialize a new RepresentationNode.

Parameters:

• node_id (str) – Unique identifier for the node

• name (str) – Name of the representation

• type (str) – Type of representation

• transform (Dict[str, List[str]], optional) – Transformation data with position, rotation, and scale

• description (str) – Description of the representation

set_transform(position: List[str] | None = None, rotation: List[str] | None = None, scale: List[str] | None = None) → None

Set the transformation parameters.

Parameters:

• position (List[str], optional) – Position [x, y, z] as strings

• rotation (List[str], optional) – Rotation [x, y, z] in radians as strings

• scale (List[str], optional) – Scale [x, y, z] as strings

to_dict() → Dict[str, Any]

Convert the node to a dictionary for JSON serialization.

Returns:

Dictionary representation of the node

Return type:

Dict[str, Any]

class s3dgraphy.nodes.representation_node.RepresentationModelNode(node_id: str, name: str, type: str = 'RM', transform: Dict[str, List[str]] | None = None, description: str = '')

Bases: RepresentationNode

Node representing a 3D model or spatialized image.

This class is used for general 3D models associated with stratigraphic units.

node_type

Type of node, set to “representation_model”

Type:

str

node_type = 'representation_model'

VALID_TYPES = {'RM': 'Representation Model - 3D Model', 'generic': 'Generic Representation', 'spatialized_image': 'Spatialized Image'}

__init__(node_id: str, name: str, type: str = 'RM', transform: Dict[str, List[str]] | None = None, description: str = '')

Initialize a new RepresentationModelNode.

Parameters:

• node_id (str) – Unique identifier for the node

• name (str) – Name of the model

• type (str) – Type of representation (“RM”, “spatialized_image”, or “generic”)

• transform (Dict[str, List[str]], optional) – Transformation data

• description (str) – Description of the model

Raises:

ValueError – If the type is not valid

class s3dgraphy.nodes.representation_node.RepresentationModelDocNode(node_id: str, name: str, type: str = 'spatialized_image', transform: Dict[str, List[str]] | None = None, description: str = '')

Bases: RepresentationNode

Node representing a 3D model or spatialized image for documents.

This class is used to instantiate documents, extractors or combiner nodes within the scene. An example is a historical photo positioned in its original position.

node_type

Type of node, set to “representation_model_doc”

Type:

str

node_type = 'representation_model_doc'

VALID_TYPES = {'RM': 'Representation Model - 3D Model', 'generic': 'Generic Representation', 'spatialized_image': 'Spatialized Image'}

__init__(node_id: str, name: str, type: str = 'spatialized_image', transform: Dict[str, List[str]] | None = None, description: str = '')

Initialize a new RepresentationModelDocNode.

Parameters:

• node_id (str) – Unique identifier for the node

• name (str) – Name of the model

• type (str) – Type of representation (“RM”, “spatialized_image”, or “generic”)

• transform (Dict[str, List[str]], optional) – Transformation data

• description (str) – Description of the model

Raises:

ValueError – If the type is not valid

class s3dgraphy.nodes.representation_node.RepresentationModelSpecialFindNode(node_id: str, name: str, type: str = 'RM', transform: Dict[str, List[str]] | None = None, description: str = '')

Bases: RepresentationNode

Node representing a 3D model for special finds.

This class is used to instantiate special finds in the scene. An example is a scanned 3D model of a capital repositioned in its original position according to an anastylosis hypothesis.

node_type

Type of node, set to “representation_model_sf”

Type:

str

node_type = 'representation_model_sf'

VALID_TYPES = {'RM': 'Representation Model - 3D Model', 'generic': 'Generic Representation', 'spatialized_image': 'Spatialized Image'}

__init__(node_id: str, name: str, type: str = 'RM', transform: Dict[str, List[str]] | None = None, description: str = '')

Initialize a new RepresentationModelSpecialFindNode.

Parameters:

• node_id (str) – Unique identifier for the node

• name (str) – Name of the model

• type (str) – Type of representation (“RM”, “spatialized_image”, or “generic”)

• transform (Dict[str, List[str]], optional) – Transformation data

• description (str) – Description of the model

Raises:

ValueError – If the type is not valid

Other Node Types

class s3dgraphy.nodes.group_node.GroupNode(node_id, name, description='', y_pos=0.0)

Bases: Node

Nodo che rappresenta un gruppo di nodi. Tali gruppi possono essere di vari tipi: vedi sottoclassi di seguito.

y_pos

Posizione verticale del nodo.

Type:

float

node_type = 'Group'

__init__(node_id, name, description='', y_pos=0.0)

class s3dgraphy.nodes.group_node.ActivityNodeGroup(node_id, name, description='', y_pos=0.0)

Bases: GroupNode

Nodo gruppo per attività. Una attività è un gruppo logico di azioni che vengono tenute insieme per un fine narrativo e di ordine delle informazioni (es: costruzione di una stanza di un edificio nell’anno x, attività di restauro di varie parti di quella stanza 20 anni dopo)

node_type = 'ActivityNodeGroup'

__init__(node_id, name, description='', y_pos=0.0)

class s3dgraphy.nodes.group_node.ParadataNodeGroup(node_id, name, description='', y_pos=0.0)

Bases: GroupNode

Nodo gruppo per paradata. Questo gruppo tiene insieme tutti i paradati relativi ad una unità stratigrafica: normalmente si chiama “[nome_US]_PD” (ParaData)

node_type = 'ParadataNodeGroup'

__init__(node_id, name, description='', y_pos=0.0)

class s3dgraphy.nodes.group_node.TimeBranchNodeGroup(node_id, name, description='', y_pos=0.0)

Bases: GroupNode

Group node to aggregate all elements belonging to a time branch. Two TB can be connected by a “contrasts_with” edge.

node_type = 'TimeBranchNodeGroup'

__init__(node_id, name, description='', y_pos=0.0)

class s3dgraphy.nodes.group_node.LocationNodeGroup(node_id, name, kind, description='', propagation='additive', y_pos=0.0)

Bases: GroupNode

Group node for spatial / locational membership of stratigraphic units and paradata. Orthogonal to ActivityNodeGroup (intention) and EpochNode (time): a Location answers the question what (named) place is this in?.

Three required kinds coexist on the same axis and may compose on the same node:

• toponym — external / administrative identity

  (Pompei, Lazio, Italia)

• study — operational / procedural identity

  (saggio, settore, quadrato, sondage)

• functional — interpretive / semantic identity

  (basilica, room A, courtyard)

Propagation is additive: multiple memberships compose, none overrides — distinct from EpochNode which is substitutive (finest-grained wins).

Membership is m:n via multiple is_in_location edges. A wall between two rooms belongs to both. The optional is_primary: True attribute on one of the edges marks the membership that should be rendered as a yEd group folder in em-graph (yEd cannot draw overlapping group folders).

Locations are hierarchical: a LocationNodeGroup can itself be is_in_location of another LocationNodeGroup (Pompei → Sector 4 → Casa del Fauno → Room 12).

A Location is identitary, not geometric. For coordinates / EPSG / shifts use the dedicated GeoPositionNode. The two concepts are linked at the CIDOC level via P161 has spatial projection (E53 Place → E94 Space Primitive).

CIDOC-CRM mapping:

• the LocationNodeGroup itself → E53 Place

• the kind attribute classifies it → E55 Type

• is_in_location (node → location) → P53 has former or current location

• is_in_location (location → location, recursive)

  → P89 falls within

• non-CIDOC fields (is_primary, propagation, kind enum value) → s3d: extension URIs

Originating discussion:

https://github.com/zalmoxes-laran/s3Dgraphy/issues/5

node_type = 'LocationNodeGroup'

VALID_KINDS = ('toponym', 'study', 'functional')

VALID_PROPAGATIONS = ('additive', 'substitutive')

__init__(node_id, name, kind, description='', propagation='additive', y_pos=0.0)

class s3dgraphy.nodes.graph_node.GraphNode(node_id, name='Graph', description='')

Bases: Node

It represents the node of the graph itself within the system. It allows the graph itself to be linked to other nodes, such as authors and licences.

node_type = 'graph'

__init__(node_id, name='Graph', description='')

class s3dgraphy.nodes.geo_position_node.GeoPositionNode(node_id, epsg=4326, shift_x=0.0, shift_y=0.0, shift_z=0.0)

Bases: Node

Classe per rappresentare un nodo GeoPosition all’interno del grafo.

Attributi:

type (str): Tipo di nodo, impostato su “geo_position”. data (dict): Dati relativi alla posizione geografica.

node_type = 'geo_position'

__init__(node_id, epsg=4326, shift_x=0.0, shift_y=0.0, shift_z=0.0)

Inizializza una nuova istanza di GeoPositionNode.

Parameters:

• node_id (str) – Identificativo univoco del nodo.

• epsg (int, opzionale) – Codice EPSG del sistema di riferimento delle coordinate. Defaults to 4326.

• shift_x (float, opzionale) – Spostamento lungo l’asse X. Defaults to 0.0.

• shift_y (float, opzionale) – Spostamento lungo l’asse Y. Defaults to 0.0.

• shift_z (float, opzionale) – Spostamento lungo l’asse Z. Defaults to 0.0.

to_dict()

Converte l’istanza di GeoPositionNode in un dizionario.

Returns:

Rappresentazione del GeoPositionNode come dizionario.

Return type:

dict

class s3dgraphy.nodes.epoch_node.EpochNode(node_id, name, start_time, end_time, color='#FFFFFF', description='')

Bases: Node

Nodo che rappresenta un’epoca temporale. Si tratta di un insieme di comodo che permette di attribuire d’ufficio una serie di azioni ad un delta temporale. Una volta che i dati puntuali sulla cronologia, espressi come proprietà start_time ed end_time delle singole US viene definito grazie ad elementi dtanti, tali nodi epoca vengono ignorati laddove ci sono i suddetti dati puntuali.

start_time

Tempo di inizio dell’epoca.

Type:

float

end_time

Tempo di fine dell’epoca.

Type:

float

color

Colore associato all’epoca.

Type:

str

node_type = 'EpochNode'

__init__(node_id, name, start_time, end_time, color='#FFFFFF', description='')

set_name(name)

set_start_time(start_time)

set_end_time(end_time)

set_color(color)