topologicpy.ShapeGrammar module

class topologicpy.ShapeGrammar.ShapeGrammar(title: str = 'Untitled', description: str = '')

Bases: object

A compiled, provenance-aware topology shape grammar.

ShapeGrammar stores rules that match a topology pattern and apply a replacement, Boolean, transform, or procedural division operation to a matching target topology.

The public API is backend-neutral. On the PythonOCC backend, rule application participates in TopologicPy’s exact native provenance path: OCCT history is captured from the operation already being executed and BRepGraph is used, when available, as the exact final-result membership index. BRepGraph and OCCT objects never appear in this public API.

Rules are compiled and indexed by topology type and structural counts. Matching therefore avoids calling Topology.IsSimilar for rules that can be rejected cheaply. Match results and rule applications are cached.

Rule geometry is treated as immutable after AddRule. If a rule input or output topology is mutated externally, call Invalidate before matching or applying rules again.

Attributes

operations: Return public operation descriptors.
rules: Return public rule descriptors in insertion order.

Methods

`AddRule`(input[, output, title, description, ...])	Add a rule and return its stable integer rule identifier.
`ApplicableRules`(topology[, keys, ...])	Return deterministic match descriptors for all applicable rules.
`Apply`(topology, rule, **kwargs)	Alias for `ApplyRule()`.
`ApplyMatch`(topology, match, **kwargs)	Apply a descriptor returned by `ApplicableRules()`.
`ApplyRule`(topology, rule[, matrix, keys, ...])	Apply one rule to `topology` and return the resulting topology.
`ClearRuntime`([clearHistory])	Clear match/application caches; optionally clear application history.
`Compile`([force])	Compile and index the current rules and return a compact summary.
`Data`([includeBREP])	Return a persistence-safe dictionary.
`DerivationGraph`()	Return the rule-application history as a topology-state `TGraph`.
`Descendants`(topology[, application])	Trace a source subtopology forward through captured lineage.
`History`([application, rule, relation, ...])	Return backend-neutral exact lineage records from rule applications.
`Invalidate`()	Invalidate compiled rule, match, and application caches.
`LineageGraph`([application, topologyType, ...])	Return exact captured subtopology lineage as a derived `TGraph`.
`Match`(topology, **kwargs)	Alias for `ApplicableRules()`.
`Origins`(topology[, application])	Trace a result subtopology backwards to terminal rule-application sources.

Application
ByData
ByJSONString
ByPath
ClearRules
ClusterByInputOutput
ClusterByRule
DeletedBy
Export
FigureByInputOutput
FigureByRule
GeneratedBy
JSONString
ModifiedBy
OperationByTitle
OperationTitles
Operations
RemoveRule
Rule
Rules
Status
UnchangedBy

AddRule(input, output=None, title: str = 'Untitled Rule', description: str = '', operation: Any = 'Replace', matrix: Optional[Sequence[Sequence[float]]] = None, uSides: int = 2, vSides: int = 2, wSides: int = 2, metadata: Optional[dict] = None, silent: bool = False) → Optional[int]

Add a rule and return its stable integer rule identifier.

input is the pattern topology. output is required by replacement and Boolean operations and is authored in the same rule-local coordinate frame as input. Transform and Divide do not use output.

ApplicableRules(topology, keys: Optional[Sequence[str]] = None, removeCoplanarFaces: bool = False, mantissa: int = 6, epsilon: float = 0.1, tolerance: float = 0.0001, cache: bool = True, silent: bool = False) → Optional[list]

Return deterministic match descriptors for all applicable rules.

Each descriptor contains rule (the rule id), matrix (the rule-input -> target similarity transform), and basic rule metadata.

Application(application: Optional[int] = None) → Optional[dict]

Apply(topology, rule, **kwargs): Alias for ApplyRule().

ApplyMatch(topology, match: dict, **kwargs): Apply a descriptor returned by ApplicableRules().

ApplyRule(topology, rule, matrix: Optional[Sequence[Sequence[float]]] = None, keys: Optional[Sequence[str]] = None, removeCoplanarFaces: bool = False, mantissa: int = 6, epsilon: float = 0.1, tolerance: float = 0.0001, force: bool = False, cache: bool = True, lineage: bool = True, silent: bool = False)

Apply one rule to topology and return the resulting topology.

rule may be a rule id, a descriptor returned by Rule, or a match descriptor returned by ApplicableRules. If matrix is omitted, the method computes the rule-input -> target match transform. Set force=True to apply with an identity match transform when the target does not match the rule input.

classmethod ByData(data: dict, silent: bool = False)

classmethod ByJSONString(string: str, silent: bool = False)

classmethod ByPath(path: str, silent: bool = False)

ClearRules() → None

ClearRuntime(clearHistory: bool = False) → None: Clear match/application caches; optionally clear application history.

ClusterByInputOutput(input, output, silent: bool = False)

ClusterByRule(rule, silent: bool = False)

Compile(force: bool = False) → dict: Compile and index the current rules and return a compact summary.

Data(includeBREP: bool = True) → dict: Return a persistence-safe dictionary. Runtime caches/history are omitted.

DeletedBy(application: Optional[int] = None, topologyType: Optional[str] = None) → list

DerivationGraph(): Return the rule-application history as a topology-state TGraph.

Descendants(topology, application: Optional[int] = None) → list: Trace a source subtopology forward through captured lineage.

Export(path: str, indent: int = 2, overwrite: bool = False, silent: bool = False) → Optional[bool]

FigureByInputOutput(input, output, silent: bool = False)

FigureByRule(rule, silent: bool = False)

GeneratedBy(application: Optional[int] = None, topologyType: Optional[str] = None) → list

History(application: Optional[int] = None, rule: Any = None, relation: Optional[str] = None, sourceRole: Optional[str] = None, resultType: Optional[str] = None) → list: Return backend-neutral exact lineage records from rule applications.

Invalidate() → None

Invalidate compiled rule, match, and application caches.

Call this after externally mutating topology dictionaries used by rules. Existing application history remains available.

JSONString(indent: Optional[int] = None) → Optional[str]

LineageGraph(application: Optional[int] = None, topologyType: Optional[str] = None, detailed: bool = False, includeDeleted: bool = False): Return exact captured subtopology lineage as a derived TGraph.

Match(topology, **kwargs): Alias for ApplicableRules().

ModifiedBy(application: Optional[int] = None, topologyType: Optional[str] = None) → list

OperationByTitle(title)

OperationTitles() → list

Operations() → list

Origins(topology, application: Optional[int] = None) → list

Trace a result subtopology backwards to terminal rule-application sources.

Identity/self-loop lineage records such as unchanged relationships are treated as terminal provenance steps rather than as upstream predecessors. This prevents a source topology from being incorrectly considered its own ancestor.

Parameters

topologytopologicpy topology: The result topology whose origins are to be traced.
applicationint, optional: If specified, restrict the search to this rule application. If None, all recorded applications are searched.

Returns

list: A list of dictionaries describing the terminal origins.

RemoveRule(rule, silent: bool = False) → bool

Rule(rule) → Optional[dict]

Rules() → list

SCHEMA = 'topologicpy.shapegrammar/2'

Status() → dict

UnchangedBy(application: Optional[int] = None, topologyType: Optional[str] = None) → list

property operations: list: Return public operation descriptors.

property rules: list: Return public rule descriptors in insertion order.