maxon.GraphDescription¶

Description¶

Provides functions and constants to read and write node graphs from and into the graph description format.

A graph description is JSON-like format to describe complete or partial node graphs for arbitrary node spaces. Graph descriptions can describe node types and their attributes over their labels in a natural language, absolute and lazy node paths, and queries to select entities in a graph by their values.

Inheritance diagram¶

Attributes¶

`maxon.GraphDescription.ClearSoloNodeCommand`	Returns the key for a clear solo node command field in a description.
`maxon.GraphDescription.ClearStartNodeCommand`	Returns the key for a clear start node command field in a description.
`maxon.GraphDescription.Commands`	Returns the key for a command field in a description.
`maxon.GraphDescription.Default`	Returns the key for an input-group default value.
`maxon.GraphDescription.DefaultCommand`	Returns the key for a default node command field in a description.
`maxon.GraphDescription.Description`	Returns the key for a description field in a description.
`maxon.GraphDescription.DisconnectCommand`	Returns the key for an isolate node command field in a description.
`maxon.GraphDescription.Enum`	Returns the key for input-group enumerations.
`maxon.GraphDescription.Flags`	Returns the key for a flags field in a description.
`maxon.GraphDescription.GroupChildren`	Returns the key for group children.
`maxon.GraphDescription.HidePortsCommand`	Returns the key for a hide ports command field in a description.
`maxon.GraphDescription.Id`	Returns the key for a node ID field in a description.
`maxon.GraphDescription.InputGroup`	Returns the key for an input-group scope.
`maxon.GraphDescription.Language`	Returns the key for a language ID field in a description.
`maxon.GraphDescription.Max`	Returns the key for an input-group maximum value.
`maxon.GraphDescription.Min`	Returns the key for an input-group minimum value.
`maxon.GraphDescription.Ports`	Returns the key for input-group ports.
`maxon.GraphDescription.Query`	Returns the key for a query field in a description.
`maxon.GraphDescription.QueryComposition`	Returns the key for a query composition field.
`maxon.GraphDescription.QueryFlags`	Returns the key for query flags.
`maxon.GraphDescription.QueryMaxError`	Returns the key for a query tolerance field.
`maxon.GraphDescription.QueryMode`	Returns the key for a query mode field in a description.
`maxon.GraphDescription.QueryOpAnd`	Returns the key for the and operator in a query.
`maxon.GraphDescription.QueryOpEqual`	Returns the key for the equal operator in a query.
`maxon.GraphDescription.QueryOpGreater`	Returns the key for the greater operator in a query.
`maxon.GraphDescription.QueryOpGreaterEqual`	Returns the key for the greater or equal operator in a query.
`maxon.GraphDescription.QueryOpLess`	Returns the key for the less operator in a query.
`maxon.GraphDescription.QueryOpLessEqual`	Returns the key for the less or equal operator in a query.
`maxon.GraphDescription.QueryOpNotEqual`	Returns the key for the not equal operator in a query.
`maxon.GraphDescription.QueryOpOr`	Returns the key for the or operator in a query.
`maxon.GraphDescription.QueryOpRegexMatch`	Returns the key for the regular expression match operator in a query.
`maxon.GraphDescription.QueryOpRegexSearch`	Returns the key for the regular expression search operator in a query.
`maxon.GraphDescription.QueryOperator`	Returns the key for a comparison operator field.
`maxon.GraphDescription.QuerySelectPorts`	Returns the key for a query select ports field.
`maxon.GraphDescription.QueryValue`	Returns the key for a comparison value field.
`maxon.GraphDescription.RecursiveUngroupCommand`	Returns the key for a recursive ungroup command field in a description.
`maxon.GraphDescription.RemoveCommand`	Returns the key for a remove node command field in a description.
`maxon.GraphDescription.SetPortCountCommand`	Returns the key for a change ports count command field in a description.
`maxon.GraphDescription.ShowPortsCommand`	Returns the key for a show ports command field in a description.
`maxon.GraphDescription.SoloNodeCommand`	Returns the key for a solo node command field in a description.
`maxon.GraphDescription.Space`	Returns the key for a node space ID field in a description.
`maxon.GraphDescription.StartNodeCommand`	Returns the key for a start node command field in a description.
`maxon.GraphDescription.Step`	Returns the key for an input-group step value.
`maxon.GraphDescription.Type`	Returns the key for a node type field in a description.
`maxon.GraphDescription.TypeBool`	Returns the input-group type string for boolean values.
`maxon.GraphDescription.TypeColor`	Returns the input-group type string for color values.
`maxon.GraphDescription.TypeColorA`	Returns the input-group type string for alpha color values.
`maxon.GraphDescription.TypeFloat`	Returns the input-group type string for float values.
`maxon.GraphDescription.TypeId`	Returns the input-group type string for ID values.
`maxon.GraphDescription.TypeInt`	Returns the input-group type string for integer values.
`maxon.GraphDescription.TypeInternedId`	Returns the input-group type string for interned ID values.
`maxon.GraphDescription.TypeString`	Returns the input-group type string for string values.
`maxon.GraphDescription.TypeUrl`	Returns the input-group type string for URL values.
`maxon.GraphDescription.TypeVector`	Returns the input-group type string for vector values.
`maxon.GraphDescription.UngroupCommand`	Returns the key for an ungroup command field in a description.

Methods Signature¶

`ApplyDescription`(graph, description[, …])	Applies the given graph description to the given nodes graph.
`CreateGraph`([element, nodeSpaceId, …])	Returns the nodes graph for the given scene #element and #nodeSpaceId.
`EvaluateQuery`(graph, query[, nodeSpace, …])	Evaluates a graph query and returns its matched nodes.
`GetGraph`([element, nodeSpaceId, …])	Returns the nodes graph for the given scene element and nodeSpaceId.
`GetMaterialGraphs`(nodeSpaceId)	Returns all material graphs in the given scene #doc which are in the given #nodeSpaceId.

Methods Definition¶

static GraphDescription.ApplyDescription(graph: maxon.frameworks.nodes.NodesGraphModelRef, description: dict, nodeSpace: str = '', language: str = '', callback: callable = None, validateAbsolutePaths: bool = True) → dict¶

Applies the given graph description to the given nodes graph.

Parameters

graph (maxon.NodesGraphModelRef) – The nodes graph to apply the description to.
description (Union[dict, list[dict]]) – The description to apply to graph.
nodeSpace (Union[str, maxon.String, maxon.Id, maxon.InternedId]) – The node space the given description is intended for. When the empty string or Id are passed, the space will be deduced from the passed graph. Apart from raising errors a bit earlier, this argument has only the function to make for more declarative code which clearly states for which node space a description is intended. Defaults to the empty string.
nodeSpace – The natural language the given description is referencing. When the empty string or Id are passed, the currently active language of Cinema 4D is used to parse the description. Only relevant when using label references. Defaults to the empty string.
callback (Union[callable, None]) – Will be called for each scope in the given description before it is parsed into the given graph. Defaults to None.
validateAbsolutePaths – When True, absolute node paths in the given description will still be validated with the underlying graph description cache. When False, absolute node paths will invoked without checking the cache. This has the advantage that one can address ports and attributes that are not cacheable. The disadvantage is that one will get less precise error messages when a cacheable path is wrong. Should only be set to False for descriptions which raise the error ‘WARNING: Failed to cache child attributes for type ‘@’ in port bundle ‘@’. Referencing its children is only possible via absolute node paths.’. And then only when one actually wants to reference one of these children. This currently happens for example in the standard renderer node space for some color ports which decompose themselves into (r, g, b) child ports. Setting the color as a whole will work, but setting one of the child ports will not unless one uses an absolute node path and sets this flag to False, so that the path is being used without being validated. Defaults to True.

Returns

All nodes in the given graph as (ID, node) key-value pairs.

Return type

dict

static GraphDescription.CreateGraph(element: c4d.BaseList2D = None, nodeSpaceId: str = '', createEmpty: bool = True, name: str = '') → maxon.frameworks.nodes.NodesGraphModelRef¶: Returns the nodes graph for the given scene #element and #nodeSpaceId.

Deprecated since version 2025.0: Use GetGraph() instead.

static GraphDescription.EvaluateQuery(graph: maxon.frameworks.nodes.NodesGraphModelRef, query: dict, nodeSpace: str = '', language: str = '', validateAbsolutePaths: bool = True) → BaseArray[GraphNode]¶

Evaluates a graph query and returns its matched nodes.

A graph query allows you to search for nodes within a graph via a node attribute or port values, and the connections between nodes. Queries can also be embedded within ApplyDescription() calls, but then cannot return query results that represent ports.

Parameters

graph (maxon.NodesGraphModelRef) – The nodes graph to evaluate the query against.
query (dict) – The query to evaluate.
nodeSpace (str) – The node space in which to evaluate the query.
language (str) – The language to use for the query.
validateAbsolutePaths (bool) – Whether to validate absolute paths in the query.

Returns

The nodes that match the query. Other than for embedded queries, this can also contain nodes that represent ports.

Return type

BaseArray[GraphNode]

static GraphDescription.GetGraph(element: c4d.BaseList2D = None, nodeSpaceId: str = '', createEmpty: bool = True, name: str = '') → maxon.frameworks.nodes.NodesGraphModelRef¶

Returns the nodes graph for the given scene element and nodeSpaceId.

The element can be a c4d.documents.BaseDocument (for the document wide scene nodes graph), a c4d.BaseObject (for capsules), or a material (for material graphs), or None (to create a material in the active document). When the passed element does not yet have a graph in the requested node space, it will be created.

Parameters

element (Union[c4d.documents.BaseDocument, c4d.BaseObject, c4d.BaseMaterial, None]) – The scene element to get the graph for. Can be None to create a material in the active document. Defaults to None.
nodeSpaceId (Union[str, maxon.String, maxon.Id, maxon.InternedId]) – The node space to retrieve the graph for. When the empty ID is passed, it will default to the active node space for materials and the neutron node space for everything else. Defaults to the empty string.
createEmpty (bool) – When True, new graphs will be created as an empty graph, when False the default graph will be created. Defaults to True.
name (str) – The name to give the material which is created when #element is the None. Will be ignored when the empty string. Defaults to the empty string.

Returns

The retrieved graph.

Return type

maxon.NodesGraphModelRef

GraphDescription.GetMaterialGraphs(nodeSpaceId: str) → BaseArray[NodesGraphModelRef]¶

Returns all material graphs in the given scene #doc which are in the given #nodeSpaceId.

Parameters

doc (c4d.documents.BaseDocument) – The document to get the material graphs from.
nodeSpaceId (str) – The node space to retrieve the graphs for. Cannot be the empty ID.

Returns

All material graphs in the given scene #doc which are of the given #nodeSpaceId.

Return type

maxon.BaseArray [maxon.NodesGraphModelRef]

Category	Option	Description
Query	Words and phrases	Search is case-insensitive. Put a phrase in quotes for an exact match. Quoted phrases require every word and disable fuzzy matching.
Terms	OR / AND	Choose whether to match any term or require all terms.
Fuzzy	On / Off	Toggle approximate and prefix matches. Quoted phrases always use strict matching.
Results	Sparse / Dense	Sparse groups multiple hits for one entity and hides its owned API members when the class or module itself matches. Dense lists each match separately.
Sort by	Type / Relevance	Group results by entity type then rank within each group, or rank all results by relevance.
Content	All / API / Manuals / Examples / Resources	Search all documentation, API documentation, manuals, the examples index, or the resources index. Code examples embedded in other sections retain their own content area.
Entity	All / Page / Module / Class / Function / Attribute / Description / Node / Symbol / Icon	Page covers results without a specific entity type. Resource entity types are available with All or Resources; API entity types are available with All or API.
Location	All / Text / Code / Name / Signature	Text covers everything outside code, names, and signatures. Name and Signature are available with All or API.