API Reference

grill.cook

Inspecting, authoring and editing foundational tools for the pipeline.

grill.cook.Repository

contextvars.ContextVar for the global asset repository location.

It’s value must always be set to a pathlib.Path.

Attention

By default, no value has been set. Ensure to set it before performing any creation operation.

Example:
>>> Repository.get()  # not set
Traceback (most recent call last):
  File "<input>", line 1, in <module>
LookupError: <ContextVar name='Repository' at 0x00000207F0A12B88>
>>> import tempfile
>>> from pathlib import Path
>>> Repository.set(Path(tempfile.mkdtemp()))
<Token var=<ContextVar name='Repository' at 0x00000213A46FF900> at 0x00000213C6A9F0C0>
>>> Repository.get()
WindowsPath('C:/Users/CHRIST~1/AppData/Local/Temp/tmp767wqaya')
grill.cook.create_many(taxon, names, labels=())[source]

Create a new taxon member for each of the provided names.

When creating hundreds or thousands of members, this provides a considerable performance improvement over create_unit().

The new members will be created as prims on the given taxon’s stage.

See also

define_taxon() create_unit()

Return type

List[Prim]

grill.cook.create_unit(taxon, name, label='')[source]

Create a unit member of the given taxon, with an optional display label.

The new member will be created as a prim on the given taxon’s stage.

See also

define_taxon() and create_many()

Parameters

  • taxon (Prim) –

  • name (str) –

  • label (str) –

Return type

Prim

grill.cook.define_taxon(stage, name, *, references=(), id_fields=mappingproxy({}))[source]

Define a new taxon group for asset taxonomy.

If an existing taxon with the provided name already exists in the stage, it is used.

The new taxon can extend from existing taxa via the references argument.

Optional field=value items can be provided for identification purposes via id_fields.

Returns

Prim representing the taxon group.

grill.cook.fetch_stage(identifier: str, context: Ar.ResolverContext = None, load=Usd.Stage.LoadAll) → Usd.Stage[source]
grill.cook.fetch_stage(identifier: grill.names.UsdAsset, context: Ar.ResolverContext = None, load=Usd.Stage.LoadAll) → Usd.Stage

Retrieve the stage whose root layer matches the given identifier.

If the layer does not exist, it is created in the repository.

If an open matching stage is found on the global cache, return it. Otherwise open it, populate the cache and return it.

Attention

identifier must be a valid grill.names.UsdAsset name.

Parameters

context (Optional[ResolverContext]) –

Return type

Stage

grill.cook.itaxa(prims, taxon, *taxa)[source]

Yields prims that are part of the given taxa.

grill.cook.spawn_unit(parent, child, path=Sdf.Path.emptyPath)[source]

Spawn a unit prim as a descendant of another.

  • Both parent and child must be existing units in the catalogue.

  • If path is not provided, the name of child will be used.

  • A valid Model Hierarchy is preserved by:

    1. Turning parent into an assembly.

    2. Ensuring intermediate prims between parent and child are also models.

    3. Setting explicit instanceable. on spawned children that are components.

grill.cook.taxonomy_context(stage)[source]

Get an edit context where edits will target this stage’s taxonomy layer.

Attention

If a valid taxonomy layer is not found on the layer stack, one is added to the stage.

Parameters

stage (Stage) –

Return type

EditContext

grill.cook.unit_asset(prim)[source]

Get the asset layer that acts as the ‘entry point’ for the given prim.

Parameters

prim (Prim) –

Return type

Layer

grill.cook.unit_context(prim)[source]

Get an edit context where edits will target this prim’s unit root layer.

Parameters

prim (Prim) –

Return type

EditContext

class grill.cook.UsdAsset(*args, sep='-', **kwargs)[source]

Specialized grill.names.CGAssetFile name object for USD asset resources.

Inheritance Diagram for UsdAsset

Inheritance diagram of grill.names.UsdAsset

This is the currency for USD asset identifiers in the pipeline.

Examples:
>>> asset_id = UsdAsset.get_default()
>>> asset_id
UsdAsset("demo-3d-abc-entity-rnd-main-atom-lead-base-whole.1.usda")
>>> asset_id.suffix = 'usdc'
>>> asset_id.version = 42
>>> asset_id
UsdAsset("demo-3d-abc-entity-rnd-main-atom-lead-base-whole.42.usdc")
>>> asset_id.suffix = 'abc'
Traceback (most recent call last):
...
ValueError: Can't set invalid name 'demo-3d-abc-entity-rnd-main-atom-lead-base-whole.42.abc' on UsdAsset("demo-3d-abc-entity-rnd-main-atom-lead-base-whole.42.usdc"). Valid convention is: '{code}-{media}-{kingdom}-{cluster}-{area}-{stream}-{item}-{step}-{variant}-{part}.{pipe}.{suffix}' with pattern: '^(?P<code>\w+)\-(?P<media>\w+)\-(?P<kingdom>\w+)\-(?P<cluster>\w+)\-(?P<area>\w+)\-(?P<stream>\w+)\-(?P<item>\w+)\-(?P<step>\w+)\-(?P<variant>\w+)\-(?P<part>\w+)(?P<pipe>(\.(?P<output>\w+))?\.(?P<version>\d+)(\.(?P<index>\d+))?)(\.(?P<suffix>sdf|usd|usda|usdc|usdz))$'

See also

grill.names.CGAsset for a description of available fields, naming.Name for an overview of the core API.

Note

This class is defined on the grill.names module but is exposed here for convenience.

Hint

For quick prototyping, grill.names.UsdAsset.get_anonymous() can be used to get temporary but valid grill identifiers.

grill.usd

Helpers for USD workflows which do not know anything about the pipeline.

grill.usd.common_paths(paths)[source]

For the given paths, get those which are the common parents.

Parameters

paths (Iterable[Path]) –

Return type

List[Path]

grill.usd.edit_context(payload: Sdf.Payload, /, prim: Usd.Prim) → Usd.EditContext[source]
grill.usd.edit_context(reference: Sdf.Reference, /, prim: Usd.Prim) → Usd.EditContext
grill.usd.edit_context(variant: Usd.VariantSet, /, layer: Sdf.Layer) → Usd.EditContext
grill.usd.edit_context(prim: Usd.Prim, /, query_filter: Usd.PrimCompositionQuery.Filter, target_predicate: typing.Callable) → Usd.EditContext

Composition arcs target layer stacks. These functions help create EditTargets for the first matching node’s root layer stack from prim’s composition arcs.

This allows for “chained” context switching while preserving the same stage objects.

Tip

You can try the below code snippet on USDView (or any other USD DCC application) Just swap the main = Usd.Stage.CreateInMemory() assignment for a stage on the viewport, e.g, for USDView:

>>> main = usdviewApi.stage

Then paste the rest of the code as-is:

https://user-images.githubusercontent.com/8294116/133999486-b13e811a-91f4-4d8c-92d9-44c1f81b82d4.gif
Example:
>>> from pxr import Usd, UsdGeom, Sdf
>>> main = Usd.Stage.CreateInMemory()
>>> # Jump between 3 different layer stacks adding variants to the same set
>>> # main [variant blue] -> reference [variant green] -> payload [variant red]
>>> referenced = Usd.Stage.CreateInMemory()
>>> referenced.SetDefaultPrim(referenced.DefinePrim("/Referenced"))
>>> reference = Sdf.Reference(referenced.GetRootLayer().identifier)
>>>
>>> payloaded = Usd.Stage.CreateInMemory()
>>> payloaded.SetDefaultPrim(payloaded.DefinePrim("/Payloaded"))
>>> payload = Sdf.Payload(payloaded.GetRootLayer().identifier)
>>>
>>> top = main.DefinePrim("/Top")
>>> top.GetReferences().AddReference(reference)
True
>>> import grill.usd as gusd
>>> with gusd.edit_context(reference, top):
...     top.GetPayloads().AddPayload(payload)
...     with gusd.edit_context(payload, top):
...         geom = UsdGeom.Sphere.Define(main, top.GetPath().AppendPath("inner/child"))
...         color = geom.GetDisplayColorAttr()
...         color_set = geom.GetPrim().GetVariantSets().AddVariantSet("color")
...         color_set.AddVariant("from_payload")
...         color_set.SetVariantSelection("from_payload")
...         with gusd.edit_context(color_set, payloaded.GetRootLayer()):  # color_set.GetVariantEditContext() would fail here
...             color.Set([(1,0,0)])
...         color_set.ClearVariantSelection()
...     color_set.AddVariant("from_reference")
...     color_set.SetVariantSelection("from_reference")
...     with gusd.edit_context(color_set, referenced.GetRootLayer()):
...         color.Set([(0,1,0)])
...     color_set.ClearVariantSelection()
...
True
>>> color_set.AddVariant("from_top")
>>> color_set.SetVariantSelection("from_top")
>>> with color_set.GetVariantEditContext():
...     color.Set([(0,0,1)])
...
>>> color_set.ClearVariantSelection()
True
>>> for each in main, referenced, payloaded:
...     print(each.GetRootLayer().ExportToString())
...
#usda 1.0
def "Top" (
    prepend references = @anon:0000019B6BE92A70:tmp.usda@
)
{
    over "inner"
    {
        over "child" (
            prepend variantSets = "color"
        )
        {
            variantSet "color" = {
                "from_top" {
                    color3f[] primvars:displayColor = [(0, 0, 1)]
                }
            }
        }
    }
}
#usda 1.0
(
    defaultPrim = "Referenced"
)
def "Referenced" (
    prepend payload = @anon:0000019B6BE93270:tmp.usda@
)
{
    over "inner"
    {
        over "child" (
            prepend variantSets = "color"
        )
        {
            variantSet "color" = {
                "from_reference" {
                    color3f[] primvars:displayColor = [(0, 1, 0)]
                }
            }
        }
    }
}
#usda 1.0
(
    defaultPrim = "Payloaded"
)
def "Payloaded"
{
    def "inner"
    {
        def Sphere "child" (
            prepend variantSets = "color"
        )
        {
            variantSet "color" = {
                "from_payload" {
                    color3f[] primvars:displayColor = [(1, 0, 0)]
                }
            }
        }
    }
}
Return type

EditContext

grill.usd.iprims(stage, root_paths=(), prune_predicate=None, traverse_predicate=<pxr.Usd._PrimFlagsConjunction object>)[source]

Convenience function that creates a generator useful for common prim traversals.

Without keyword arguments, this is the same as calling Usd.Stage.Traverse(…), so use that instead when no root_paths or prune_predicates are needed.

Parameters
Return type

Iterator[Prim]

← End to End Example