Blender V5.3
usd_instancing_utils.cc
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2025 NVIDIA Corporation. All rights reserved.
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
6
7#include "usd.hh"
8#include "usd_utils.hh"
9
10#include "BLI_map.hh"
11#include "BLI_set.hh"
12
13#include <pxr/usd/sdf/copyUtils.h>
14#include <pxr/usd/sdf/path.h>
15#include <pxr/usd/usd/primCompositionQuery.h>
16#include <pxr/usd/usd/primRange.h>
17#include <pxr/usd/usd/references.h>
18
19#include <string>
20
21#include "CLG_log.h"
22
23namespace blender {
24
25static CLG_LogRef LOG = {"io.usd"};
26
27namespace io::usd {
28
29/* We need an ordered map so we use std::map. */
30using PathMap = std::map<pxr::SdfPath, pxr::SdfPath>;
32
33/* Map an instanceable prim path to a list of prototype prim paths. */
35
36/* Convert the given prototype prim to an instance by deleting its children and making
37 * it an instanceable reference to the prim at ref_path. */
38static void convert_proto_to_instance(pxr::UsdStageRefPtr stage,
39 const pxr::SdfPath &proto_path,
40 const pxr::SdfPath &ref_path)
41{
42 pxr::UsdPrim proto_prim = stage->GetPrimAtPath(proto_path);
43
44 if (!proto_prim) {
45 CLOG_ERROR(&LOG, "Couldn't find prototype prim %s", proto_path.GetAsString().c_str());
46 return;
47 }
48
49 /* Collect child paths. */
50 pxr::SdfPathVector child_paths;
51 pxr::UsdPrimSiblingRange children = proto_prim.GetFilteredChildren(
52 pxr::Usd_PrimFlagsPredicate());
53 for (const auto &child_prim : children) {
54 child_paths.push_back(child_prim.GetPath());
55 }
56
57 /* Remove children from the sage. */
58 for (const pxr::SdfPath &child_path : child_paths) {
59 stage->RemovePrim(child_path);
60 }
61
62 proto_prim.GetReferences().AddInternalReference(pxr::SdfPath(ref_path));
63 proto_prim.SetInstanceable(true);
64}
65
66void process_scene_graph_instances(const USDExportParams &export_params, pxr::UsdStageRefPtr stage)
67{
68 if (!stage) {
69 return;
70 }
71
72 /* Collect paths to instanceable references and prototypes. */
73 PathSet protos;
74 /* Map an instance to the prototypes it references. */
75 ReferencesMap references_map;
76
77 pxr::UsdPrimRange range(stage->GetPseudoRoot());
78 for (pxr::UsdPrim prim : range) {
79 if (prim.IsInstanceable()) {
80 /* Get the prototypes referenced by this prim. */
81 pxr::UsdPrimCompositionQuery query = pxr::UsdPrimCompositionQuery::GetDirectReferences(prim);
82 Vector<pxr::SdfPath> references;
83 for (const auto &arc : query.GetCompositionArcs()) {
84 pxr::SdfPath target_prim_path = arc.GetTargetPrimPath();
85 protos.add(target_prim_path);
86 references.append(target_prim_path);
87 }
88 references_map.add(prim.GetPath(), references);
89 }
90 }
91
92 if (protos.is_empty()) {
93 /* No prototypes to move. */
94 return;
95 }
96
97 /* Map an original prototype path to the location where it will be copied. */
98 PathMap proto_to_copy_map;
99
100 std::string protos_root_str(export_params.root_prim_path);
101 protos_root_str += "/prototypes";
102 pxr::SdfPath protos_root_path = get_unique_path(stage, protos_root_str);
103
104 /* Create the abstract prim under which prototypes will be copied. */
105 if (!stage->CreateClassPrim(protos_root_path)) {
106 CLOG_ERROR(&LOG, "Couldn't create class prim %s.", protos_root_path.GetAsString().c_str());
107 return;
108 }
109
110 /*
111 * For each original prototype, create a placeholder Xform prim under the protos root
112 * which will be the new location where the prototype will be copied.
113 */
114 for (const pxr::SdfPath &proto_path : protos) {
115 pxr::SdfPath copy_path = protos_root_path;
116
117 copy_path = copy_path.AppendChild(proto_path.GetNameToken());
118 copy_path = get_unique_path(stage, copy_path.GetAsString());
119
120 /* Create the placeholder prim. */
121 static pxr::TfToken xform_type_tok("Xform");
122 pxr::UsdPrim dest_prim = stage->DefinePrim(copy_path, xform_type_tok);
123 if (!dest_prim) {
125 "Couldn't create destination prim %s for copying prototype %s",
126 copy_path.GetAsString().c_str(),
127 proto_path.GetAsString().c_str());
128 continue;
129 }
130
131 /* Record where original prototype path will be copied. */
132 proto_to_copy_map.insert(std::make_pair(proto_path, dest_prim.GetPath()));
133 }
134
135 /* Update all references to point to new prototype locations. */
136 for (const auto item : references_map.items()) {
137 pxr::SdfPath inst_path = item.key;
138 pxr::UsdPrim inst_prim = stage->GetPrimAtPath(item.key);
139 if (!inst_prim) {
140 CLOG_ERROR(&LOG, "Couldn't get prim for instance %s.", inst_path.GetAsString().c_str());
141 continue;
142 }
143
144 /* Updated references pointing to new prototype locations. */
145 Vector<pxr::SdfPath> new_ref_targets;
146 const Vector<pxr::SdfPath> &ref_targets = item.value;
147 for (const pxr::SdfPath &target_path : ref_targets) {
148 PathMap::const_iterator iter = proto_to_copy_map.find(target_path);
149 if (iter != proto_to_copy_map.end()) {
150 new_ref_targets.append(iter->second);
151 }
152 }
153
154 /* Replace existing references with the updated ones. */
155 if (!new_ref_targets.is_empty()) {
156 pxr::UsdReferences refs = inst_prim.GetReferences();
157 refs.ClearReferences();
158 for (const pxr::SdfPath &target : new_ref_targets) {
159 refs.AddInternalReference(target);
160 }
161 }
162 }
163
164 /*
165 * Copy the original prototypes to their new locations and update
166 * the original prototype roots to be references to the new locations.
167 * Since prototypes may be nested, we must copy the most nested prototypes
168 * first by iterating backwards through the sorted prototype map.
169 */
170 for (PathMap::reverse_iterator riter = proto_to_copy_map.rbegin();
171 riter != proto_to_copy_map.rend();
172 ++riter)
173 {
174 const pxr::SdfPath &src_path = riter->first;
175 const pxr::SdfPath &dst_path = riter->second;
176 if (!pxr::SdfCopySpec(
177 stage->GetRootLayer(), riter->first, stage->GetRootLayer(), riter->second))
178 {
179 CLOG_WARN(&LOG,
180 "Couldn't copy prim %s to %s",
181 src_path.GetAsString().c_str(),
182 dst_path.GetAsString().c_str());
183 continue;
184 }
185
186 convert_proto_to_instance(stage, src_path, dst_path);
187 }
188}
189
190} // namespace io::usd
191} // namespace blender
#define CLOG_ERROR(clg_ref,...)
Definition CLG_log.h:188
#define CLOG_WARN(clg_ref,...)
Definition CLG_log.h:189
bool add(const Key &key, const Value &value)
Definition BLI_map.hh:295
ItemIterator items() const &
Definition BLI_map.hh:902
bool add(const Key &key)
Definition BLI_set.hh:248
bool is_empty() const
Definition BLI_set.hh:614
void append(const T &value)
bool is_empty() const
pxr::SdfPath get_unique_path(pxr::UsdStageRefPtr stage, const std::string &path)
Definition usd_utils.cc:109
Map< pxr::SdfPath, Vector< pxr::SdfPath > > ReferencesMap
static void convert_proto_to_instance(pxr::UsdStageRefPtr stage, const pxr::SdfPath &proto_path, const pxr::SdfPath &ref_path)
void process_scene_graph_instances(const USDExportParams &export_params, pxr::UsdStageRefPtr stage)
Set< pxr::SdfPath > PathSet
std::map< pxr::SdfPath, pxr::SdfPath > PathMap
BMesh Iterators.
static CLG_LogRef LOG
Definition logging.cpp:12