user: Give a detailed overview of Import Options: syntax, arguments, return values, common patterns.

assistant: The following options are available when importing from USD:

### General

Path Mask
:   Import only the subset of the USD scene rooted at the given primitive.

Include
:   Visible Primitives Only
    :   Do not import invisible USD primitives. Only applies to primitives with a non-animated
        [visibility](https://graphics.pixar.com/usd/release/glossary.html#USDGlossary-Visibility) attribute.
        Primitives with animated visibility will always be imported.

    Defined Primitives Only
    :   When disabled this allows importing USD primitives
        which are not defined, such as those with an override specifier.

Set Frame Range
:   Update the scene’s start and end frame to match those of the USD stage.

Create Collection
:   Add all imported objects to a new collection.

Relative Path
:   Select the file relative to the blend-file.

Apply Unit Conversion Scale
:   Scale the scene objects by the USD Stage `metersPerUnit` value. This scaling is applied in addition to the value
    specified in the Scale option.

Scale
:   Value by which to scale the imported objects in relation to the world’s origin.

Light Intensity Scale
:   Scale for the intensity of imported lights.

Custom Properties
:   Behavior when importing USD attributes as [Custom Properties](../custom_properties.html#files-data-blocks-custom-properties).

    None:
    :   Does not import USD custom attributes.

    User:
    :   Imports USD attributes in the `userProperties` namespace as custom properties.
        The namespace will be stripped from the property names.

    All Custom:
    :   Imports all USD custom attributes as custom properties.
        Namespaces will be retained in the property names.

### Object Types

Cameras
:   Import `UsdGeomCamera` primitives as [Camera Objects](../../render/cameras.html).

    Supported camera attributes include:

    - Projection type (perspective and orthographic)
    - Focal length.
    - Depth of field distance.
    - F-stop (aperture).
    - Clipping start and end.
    - Sensor shift (tilt) X and Y.
    - Sensor size (aperture width and height).

Curves
:   Import `UsdGeomBasisCurves` primitives as [Curves](../../modeling/curves_new/index.html) and `UsdGeomNurbsCurves`
    as Blender meshes.

Lights
:   Import lights as [Light Objects](../../render/lights/index.html). Does not currently include cylinder or geometry
    lights.

World Dome Light
:   Converts the first discovered `UsdLuxDomeLight` or `UsdLuxDomeLight_1` dome light into a
    [world background shader](../../render/lights/world.html).

Materials
:   Import [UsdPreviewSurface](https://openusd.org/release/spec_usdpreviewsurface.html) materials.

Meshes
:   Import `UsdGeomMesh` primitives as [Mesh Objects](../../modeling/meshes/index.html).

Volumes
:   Import `UsdVolVolume` OpenVDB assets as [Volume Objects](../../modeling/volumes/index.html).

Point Clouds
:   Import `UsdGeomPoints` primitives as [Point Cloud Objects](../../modeling/point_cloud/index.html).

USD Shapes
:   Import USD primitive shapes as Blender meshes.
    `UsdGeomCapsule`, `UsdGeomCapsule_1`, `UsdGeomCone`, `UsdGeomCube`, `UsdGeomCylinder`,
    `UsdGeomCylinder_1`, `UsdGeomPlane`, and `UsdGeomSphere` are supported.

[Display Purpose](https://graphics.pixar.com/usd/release/glossary.html#USDGlossary-Purpose)
:   Render
    :   Include primitives with purpose `render`.

    Proxy
    :   Include primitives with purpose `proxy`.

    Guide
    :   Include primitives with purpose `guide`.

Material Purpose
:   Attempt to import materials with the given purpose.
    If no material with this purpose is bound to the primitive, then the fallback behavior, if any, is noted below.

    All Purpose:
    :   Attempt to import `allPurpose` materials.

    Preview:
    :   Attempt to import `preview` materials. Load `allPurpose` materials as a fallback.

    Full:
    :   Attempt to import `full` materials. Load `allPurpose` or `preview` materials, in that order, as a
        “fallback.”

### Geometry

UV Coordinates
:   Read mesh UV coordinates.

Color Attributes
:   Convert the USD mesh `displayColor` values to Blender’s Color Attributes.

Mesh Attributes
:   Read USD `Primvars` as mesh attributes.

Subdivision
:   Create Subdivision Surface modifiers based on the USD `SubdivisionScheme` attribute.

Validate Meshes
:   Check the imported mesh for corrupt data and fix it if necessary.
    When disabled, erroneous data may cause crashes displaying or editing the meshes.
    This option will make the importing slower but is recommended, as data errors are not always obvious.

Merge parent Xform
:   Allow USD primitives to merge with their Xform parent if they are the only child in the hierarchy.

### Rigging

Shape Keys
:   Imports USD blend shapes as Blender’s [Shape Keys](../../animation/shape_keys/index.html).

Armatures
:   Imports USD skeletons as Blender’s [Armatures](../../animation/armatures/index.html).

### Materials

Import All Materials
:   Also import materials that are not used by any geometry.
    Note, when this option is false, materials referenced by geometry will still be imported.

Import USD Preview
:   Convert USD Preview Surface shaders to Principled BSDF shader networks.

Set Material Blend
:   If the *Import USD Preview* option is enabled, the material blend method will automatically be set based on
    the `opacity` and `opacityThreshold` shader inputs, allowing for visualization of transparent objects.

Material Name Collision
:   Behavior when the name of an imported material conflicts with an existing material.

    Make Unique:
    :   Import each USD material as a unique Blender material.

    Reference Existing:
    :   If a material with the same name already exists, reference that instead of importing.

### Textures

When importing a USDZ package, the following options specify whether and how texture asset dependencies
of the USD should be copied from the zip archive so they can be loaded into Blender.

Import Textures
:   Behavior when importing textures from a USDZ archive.

    None:
    :   Don’t import textures. Note that, with this option, material textures may fail to be resolved in Blender.

    Packed:
    :   Import textures as packed data in the Blender file.

    Copy:
    :   Copy files to the directory specified in the **Textures Directory** option.

Textures Directory
:   Path to the directory where imported textures will be copied, when the **Import Textures** mode is **Copy**.

    Note that the default textures directory is the relative path `//textures`, which requires the
    Blender file to have been saved before importing, so the relative path can be resolved.

File Name Collision
:   Behavior when the name of an imported texture file conflicts with an existing file.

    Use Existing:
    :   If a file with the same name already exists, use that instead of copying.

    Overwrite:
    :   Overwrite existing files.

### Particles and Instancing

Scene Instancing
:   Import USD scene graph instances as collection instances, otherwise they are imported as copies.