General content improvements from feedback (#51)

* General content improvements from feedback
* Update model-viewer from 3.5.0 to 4.1.0
* Add support for playback of multiple animations at once.
* Add tone-mapping to maintain rendering consistency in model-viewer 4.1.0 upgrade.

Signed-off-by: Matias Codesal <mcodesal@nvidia.com>

Author: mati-nvidia

docs/asset-modularity-instancing/authoring-point-instancing/point-instancing-intro.md

@@ -12,7 +12,7 @@ See the {usdcpp}`UsdGeomPointInstancer Details` documentation to learn more abou
 
 Compared to [scenegraph instancing](../authoring-scenegraph-instancing/scenegraph-instancing-intro.md), PointInstancers can be less user-friendly and trickier to refine because most of scene description is hidden away in large arrays that are not as human-readable. 
 
-Point instancing is designed for massive numbers of simpler items where the overhead of an instance outweights the benefits of reuse. What does this mean? Think about leaves on a tree. You might have a 100,000 leaves on a tree. If you started down the path of using scenegraph instancing for this, you would need to define each leaf repetition and you would end up with 100,000 {term}`instanceable <Instanceable>` prims: "Leaf_000001", "Leaf_000002", "Leaf_000003", etc. Do you really need this in your scenegraph? Is this useful data for anyone?
+Point instancing is designed for massive numbers of simpler items where the overhead of an instance outweighs the benefits of reuse. What does this mean? Think about leaves on a tree. You might have a 100,000 leaves on a tree. If you started down the path of using scenegraph instancing for this, you would need to define each leaf repetition and you would end up with 100,000 {term}`instanceable <Instanceable>` prims: "Leaf_000001", "Leaf_000002", "Leaf_000003", etc. Do you really need this in your scenegraph? Is this useful data for anyone?
 
 That's where point instancing is a clear winner.
 
@@ -102,4 +102,23 @@ over "PackingPeanuts"
 }
 ```
 
-Keep this in mind as you perform downstream overrides and considerations you may need to make about things like USD {term}`layers <Layer>` format (i.e. USDA vs {term}`USDC <Crate File Format>`).
+Keep this in mind as you perform downstream overrides and considerations you may need to make about things like USD {term}`layers <Layer>` format (i.e. USDA vs {term}`USDC <Crate File Format>`).
+
+## Computing Instance Transforms
+
+When you specify `positions` on a PointInstancer, you're defining positions in the PointInstancer's local coordinate space. However, when USD computes the final world-space position of each instance, it combines multiple transforms together.
+
+For each instance, USD applies the following transforms in order from most local to least local:
+
+1. **Prototype root transform**: The local-to-parent transformation of the prototype root is applied most locally.
+2. **Instance-specific transforms**: The per-instance transformation is applied next, in this order:
+   - `scales[i]` (if authored)
+   - `orientations[i]` (if authored)
+   - `positions[i]`
+3. **PointInstancer prim transform**: The transformation authored on the PointInstancer prim itself is applied least locally.
+
+This means that you can move an entire PointInstancer around your scene by transforming the PointInstancer prim, and you can have prototypes with their own local transforms that will be incorporated into each instance's final position.
+
+```{seealso}
+For the complete details on how instance transforms are computed, including handling of velocities and angular velocities, see the {usdcpp}`UsdGeomPointInstancer` documentation.
+```

docs/asset-modularity-instancing/instancing-faq.md

@@ -16,4 +16,4 @@
 * Instances identifiable via index
 * Invasive deinstancing
 * May be combined with scenegraph instancing
-* Good for massive numbers of simpler items where the overhead of an instance outweights the benefits of reuse. (e.g. leaves on trees)
+* Good for massive numbers of simpler items where the overhead of an instance outweighs the benefits of reuse. (e.g. leaves on trees)

docs/asset-modularity-instancing/refining-point-instances.md

@@ -101,11 +101,28 @@ box = stage.DefinePrim("/World/CubeBox_A04_26cm_01")
 stage_path = Path(stage.GetRootLayer().identifier)
 box_asset_path = stage_path.parent.parent / "src_assets" / "Assets" / "Components" / "CubeBox_A04_26cm" / "CubeBox_A04_26cm.usd"
 box.GetReferences().AddReference(str(box_asset_path))
+# Compute the transform for the instances.
+# This is more robust than GetPositionsAttr as it accounts for the prototype's transform and velocities too.
+xforms = pi.ComputeInstanceTransformsAtTime(
+  Usd.TimeCode.Default(), 
+  Usd.TimeCode.Default(), 
+  # We can ignore the mask to query the previously deactivated instance
+  applyMask=UsdGeom.PointInstancer.IgnoreMask)
+world_transform = xforms[1228]
+# Extract translation, rotation, and scale from the matrix
+translation = world_transform.ExtractTranslation()
+rotation = world_transform.ExtractRotation()
+scale = Gf.Vec3d(*(v.GetLength() for v in world_transform.ExtractRotationMatrix()))
+
+# Apply the computed transform to the promoted box using Xformable API
 box_xform = UsdGeom.Xformable(box)
-box_xform.GetTranslateOp().Set(pi.GetPositionsAttr().Get()[1228])
-box_xform.AddOrientOp(precision=UsdGeom.XformOp.PrecisionHalf).Set(pi.GetOrientationsAttr().Get()[1228])
+box_xform.GetTranslateOp().Set(translation)
+box_xform.AddOrientOp().Set(Gf.Quatf(rotation.GetQuat()))
+box_xform.AddScaleOp().Set(scale)
 ```
 
+This approach uses `ComputeInstanceTransformsAtTime()` to get the complete transform matrix for instance `1228`, which automatically combines the prototype root transform and the instance-specific transform (positions, velocities, orientations, angularVelocities, scales). This is still slightly simplified because we did not account for the PointInstancer prim's transformations. In this case, it's ok because the PointInstancer is at the origin.
+
 The box looks just like it did before in the Viewport, but now we have a new prim hierarchy in the scenegraph where we can author new {term}`opinions <Opinions>` to manipulate this asset.
 
 ![](../images/asset-modularity-instancing/promotion.png)

docs/asset-modularity-instancing/refining-scenegraph-instances/scenegraph-deinstance-refinement.md

@@ -8,7 +8,7 @@ The simplest way to edit or override an instance is to disable instancing for th
 Deinstance refinement
 ```
 
-At any point downstream, we can enable or disable instancing on a {term}`prim <Prim>`. If we have a use case where we just need to open one box, what we'll do is we'll set `instanceable = false` and now we can apply the overrides to open thet box. 
+At any point downstream, we can enable or disable instancing on a {term}`prim <Prim>`. If we have a use case where we just need to open one box, what we'll do is we'll set `instanceable = false` and now we can apply the overrides to open that box. 
 
 If you just have one thing that needs to be promoted to be treated uniquely from the rest of the copies, it's totally reasonable to deinstance it in a stronger {term}`layer <Layer>`.
 

docs/beyond-basics/custom-properties.md

@@ -65,6 +65,12 @@ Custom properties are the easiest and most flexible way to adapt OpenUSD to spec
 We often recommend custom properties instead of metadata or `customData` metadata for prototyping because the former requires plugin-based schema development which is less portable and the later is more costly for composition because it is a composable dictionary data type.
 ```
 
+### Grouping Related Properties
+
+Namespace prefixes provide a way to logically group related properties together on a single prim. This is especially useful when working with data from other sources that have compound or structured types (like structs, records, or grouped fields). Since USD doesn't have a native struct type, namespace-prefixed attributes serve as the standard convention for representing this kind of grouped data.
+
+You can even use nested namespaces to create a hierarchical organization. For example, sensor readings from an IoT device might be organized as `acme:sensor:temperature`, `acme:sensor:humidity`, and `acme:sensor:pressure`. Here, `acme:` identifies your organization and `sensor:` groups the related properties—the combined prefix makes it clear both where the data originated and that these attributes belong together conceptually. This approach is particularly valuable in data exchange workflows where you need to map complex data models from other formats into OpenUSD.
+
 ## Working With Python
 
 ![Custom Attribute Python](../images/foundations/CustomAttribute_Python.webm)
@@ -194,6 +200,59 @@ stage.Save()
 DisplayUSD(file_path, show_usd_code=True)
 ```
 
+### Example 3: Grouping Related Properties with Namespaces
+
+When working with grouped or compound data from other sources, namespace-prefixed attributes provide a clean way to organize related properties together. This example demonstrates how to store sensor readings using namespace prefixes.
+
+Notice the double namespacing pattern `acme:sensor:temperature`. The first namespace (`acme:`) identifies the organization that created these custom properties, while the second namespace (`sensor:`) groups related properties together. This hierarchical approach allows you to both claim ownership of your custom properties and logically organize them into functional groups. It's a common pattern when mapping compound data types from other formats into USD.
+
+```{code-cell}
+:emphasize-lines: 9-20
+
+from pxr import Usd, UsdGeom, Sdf
+
+file_path = "_assets/sensor_data.usda"
+stage: Usd.Stage = Usd.Stage.CreateNew(file_path)
+
+# Create a prim to represent a sensor device
+sensor_prim = stage.DefinePrim("/EnvironmentSensor", "Xform")
+
+# Group related sensor readings using namespaces: "acme:sensor:"
+# "acme" identifies the organization, "sensor" groups the related properties
+temperature = sensor_prim.CreateAttribute("acme:sensor:temperature", Sdf.ValueTypeNames.Float, custom=True)
+humidity = sensor_prim.CreateAttribute("acme:sensor:humidity", Sdf.ValueTypeNames.Float, custom=True)
+pressure = sensor_prim.CreateAttribute("acme:sensor:pressure", Sdf.ValueTypeNames.Float, custom=True)
+timestamp = sensor_prim.CreateAttribute("acme:sensor:timestamp", Sdf.ValueTypeNames.String, custom=True)
+
+# Document the custom properties to describe their purpose and units
+temperature.SetDocumentation("Temperature reading in degrees Celsius")
+humidity.SetDocumentation("Relative humidity as a percentage (0-100)")
+pressure.SetDocumentation("Atmospheric pressure in kilopascals (kPa)")
+timestamp.SetDocumentation("ISO 8601 formatted timestamp of the sensor reading")
+
+# Set sensor readings
+temperature.Set(22.5)
+humidity.Set(45.0)
+pressure.Set(101.3)
+timestamp.Set("2025-01-09T14:30:00Z")
+
+# Print grouped sensor data
+print("Sensor Readings:")
+print(f"  Temperature: {temperature.Get()}°C")
+print(f"  Humidity: {humidity.Get()}%")
+print(f"  Pressure: {pressure.Get()} kPa")
+print(f"  Timestamp: {timestamp.Get()}")
+
+stage.Save()
+```
+
+```{code-cell}
+:tags: [remove-input]
+DisplayCode(file_path)
+```
+
+Notice how all the sensor-related attributes share the `acme:sensor:` prefix. The nested namespace structure (`organization:group:property`) makes it immediately clear both where these properties came from and that they belong together as a logical group, even though they're separate attributes. This pattern is especially useful when mapping structured data types (like structs or records) from other data sources into USD.
+
 ## Key Takeaways
 
 Custom properties in OpenUSD provide a versatile way to extend the functionality of scene descriptions, making them adaptable to various specialized needs. By understanding how to create, set, and retrieve custom properties, we can enhance our OpenUSD workflows and better manage complex data in our projects, significantly improve the precision and efficiency of digital models, and build USD pipelines that are tailored to specific use

docs/beyond-basics/index.md

@@ -13,6 +13,7 @@ By the end of this module, you'll understand how to:
 - **Utilize {term}`model <Model>` {term}`kinds <Kind>`** - structure assets using {term}`component <Component>`, {term}`assembly <Assembly>`, and {term}`group <Group>` hierarchies
 - **{term}`Traverse stages <Stage Traversal>`** - implement high-performance iteration through complex scene graphs
 - **Understand {term}`Hydra <Hydra>` rendering** - work with USD's flexible rendering architecture and multiple backends
+- **Handle units in USD** - work with `metersPerUnit`, `upAxis`, `timeCodesPerSecond`, and understand automatic vs. manual unit reconciliation during composition
 
 ## Why These Skills Matter
 
@@ -39,4 +40,5 @@ active-inactive-prims
 model-kinds
 stage-traversal
 hydra
+units
 :::