user: Give a detailed overview of Importing USD Files: syntax, arguments, return values, common patterns.

assistant: [USD](https://graphics.pixar.com/usd/release/index.html) files typically represent the scene as
a hierarchy of primitives, or [prims](https://graphics.pixar.com/usd/release/glossary.html#USDGlossary-Prim).
Individual prims contain data to describe scene entities, such as geometry, lights, cameras and transform hierarchies.
Blender’s USD importer converts USD prims to a hierarchy of Blender objects. Like the USD exporter,
the importer does not yet handle certain USD composition concepts, such as layers and references.

The following USD data types can be imported as Blender objects:

- Cameras
- Curves
- Lights
- Materials
- Meshes
- Point Clouds
- Primitive Shapes
- Volumes

For more information on how the various data types are handled,
see the following descriptions of the [Import Options](#import-options).

### Xform and Scope Primitives

USD provides an `Xform` prim type, containing transform data, which can be
used to represent transform hierarchies and to organize the scene.
Such `Xform` prims are imported as Blender empty objects.

USD also supports `Scope` primitives, which are entities
that do not contain transform data, but which serve to group other element of the scene.
Blender doesn’t have an exact counterpart to the concept of a scope,
so such primitives are imported as Blender empties located at the origin.
This is an imperfect representation, because empty objects have a transform and `Scopes` do not,
but this approach nonetheless helps preserve the structure of the scene hierarchy.

### PointInstancer Primitives

USD provides a `UsdGeomPointInstancer` prim type,
containing instances that are scattered on a primitive’s points.

These are imported into Blender as Point Clouds using a
[Geometry Nodes Modifier](../../modeling/modifiers/geometry_nodes.xhtml)
and the [Instance on Points Node](../../modeling/geometry_nodes/instances/instance_on_points.xhtml).

### Animations

The importer supports two types of animation:

- **Animating transforms**: If a USD primitive has time-varying transform data,
  a [Transform Cache](../../animation/constraints/transform/transform_cache.xhtml) constraint
  will be added to the imported Blender object.
- **Animating geometry**: Animated mesh, curve, and point cloud geometry is supported by adding
  a [Mesh Sequence Cache](../../modeling/modifiers/modify/mesh_sequence_cache.xhtml) modifier to the imported data.
  Geometry attribute ([USD Primvar](https://graphics.pixar.com/usd/release/glossary.html#USDGlossary-Primvar))
  animation is supported for all data types which have corresponding Blender equivalents. This includes
  colors, UVs, velocities, and other generic attribute data.
  Note that USD file sequences (i.e. a unique file per frame) are not supported.

### Materials

If a USD mesh or geometry subset has a bound material, the importer will assign to
the Blender object a material with the same name as the USD material.
If a Blender material with the same name already exists in the scene, the existing material may be used,
depending on the [Material Name Collision](#usd-material-name-collision) option.
Otherwise, a new material will be created.

If the USD material has
a [USD Preview Surface](https://graphics.pixar.com/usd/release/spec_usdpreviewsurface.html) shader source,
the [Viewport Display](../../render/materials/settings.xhtml#render-materials-settings-viewport-display) color, metallic, and roughness are set to
the corresponding USD Preview Surface input values.

There is also an *Import USD Preview* option to convert USD Preview Surface shaders
to Blender [Principled BSDF](../../render/shader_nodes/shader/principled.xhtml) shader nodes.
This option can be lossy, as it does not yet handle converting all shader settings and types,
but it can generate approximate visualizations of the materials.

### Coordinate System Orientation

If the imported USD is Y up, a rotation will be automatically applied to
root objects to convert to Blender’s Z up orientation.