> For the complete documentation index, see [llms.txt](https://stage-precision.gitbook.io/grid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stage-precision.gitbook.io/grid/timeline/importing-timeline-data/importing-fbx-data.md). # Importing FBX Data Import FBX objects, hierarchies, Cameras, Meshes, and animation into Grid Studio, merge animation with existing objects, and create either editable Keyframes or optimized Recording data.
FBX files can be imported into Grid Studio to create object structures and bring external animation data directly onto a Timeline. Depending on the import settings, Grid Studio can: * create new objects from the FBX structure * merge animation onto existing Grid Studio objects * recreate Parent / Child hierarchies * import Polygon / Mesh objects * import Cameras * create regular editable Keyframes * import animation into the optimized Recording format This makes it possible to bring complete animated scenes into Grid Studio or use FBX animation to drive objects that already exist in the project. *** ## Starting an FBX Import There are two ways to start an FBX import. #### Drag & Drop Drag an `.fbx` file directly onto Grid Studio. #### File Menu Open: **File → Import** and select the FBX file. Both methods open the **FBX Settings** dialog before the import is executed. {% hint style="warning" %} FBX imports cannot be undone using **Undo / CTRL + Z**. Especially before larger imports or when merging FBX data into an existing project structure, save the project before starting the import. {% endhint %} After confirming the FBX Settings dialog, the import starts immediately. There is no additional Preview or confirmation step. *** ## Choose the Import Position The **Timeline Position** setting defines where Frame 0 of the FBX animation is placed on the Timeline. Available options are: * **Start** * **Current Time** * **Custom Time** #### Start **Start** places FBX Frame 0 at: `00:00:00` This is an absolute Timeline position and does not refer to the configured Timeline Start Time. #### Current Time **Current Time** places FBX Frame 0 at the current Playhead position of the selected Timeline. For example, if the Playhead is currently at: `00:05:30` the beginning of the imported FBX animation is placed at that position. If no Timeline is selected, Grid Studio creates a new Timeline and places Frame 0 at: `00:00:00` #### Custom Time **Custom Time** uses the **Custom Start Time** field to define the exact Timeline position of FBX Frame 0. If no Timeline is selected, Grid Studio creates a new Timeline and places the imported animation at the configured Custom Start Time. *** ## Choose the Import Destination FBX animation can either be imported into an existing Timeline, into an existing Parameter Layer, or into newly created Timeline structures. The relevant settings are: * **Sequence** * **Extend Parameter** #### Sequence **Sequence** selects the Timeline that should receive the imported animation. If a Sequence is selected and **Extend Parameter** is empty, Grid Studio automatically creates a new Parameter Layer inside that Timeline. #### Extend Parameter **Extend Parameter** selects an existing **Parameter Layer** as the destination for the imported animation. The imported animation is added directly to that Layer. If an existing Parameter Layer is selected, a separate Sequence selection is normally not required because the destination Layer already defines the Timeline. {% hint style="info" %} For a clear import setup, choose either: * a **Sequence** to create a new Parameter Layer inside an existing Timeline, or * **Extend Parameter** to import directly into an existing Parameter Layer. {% endhint %} #### Create a New Timeline If both **Sequence** and **Extend Parameter** are left empty, Grid Studio creates: * a new Timeline * a new Parameter Layer and imports the FBX data into that new structure. *** ## Importing Objects FBX files can contain several types of scene objects and hierarchies. When Grid Studio creates new objects from the FBX, their names and Parent / Child structure are preserved. #### Null Objects The **Import Null Objects** setting defines which Grid Studio object type should be created for FBX Null objects. Nulls can be imported as: * **Folder** * **Tracker** Use **Folder** when the FBX Null should remain a hierarchy or container object. Use **Tracker** when the imported Null should become a Tracker object in Grid Studio. #### Polygon and Mesh Objects Polygon / Mesh objects can be imported directly from the FBX. When a new Grid Studio object is created from the FBX, the actual **Mesh geometry** is imported together with the object. #### Cameras FBX Camera objects can also be imported. Supported Camera animation data includes values such as: * Transform * Field of View * Focus Distance #### Parent / Child Hierarchy When new objects are created, the Parent / Child hierarchy from the FBX is reproduced in the Grid Studio Project Tree. This allows complete FBX structures to be recreated instead of importing every object as an independent element. #### Coordinate System and Units Axis and unit conversion are handled automatically through the FBX format. No manual pre-conversion of axes or units is required before importing the file into Grid Studio. *** ## Merging with Existing Objects The **Merge With Existing** setting controls how the FBX structure is matched against objects that already exist in the Grid Studio project. Available modes are: * **None** * **Merge by Name** * **Merge by Path and Name** * **Only add Keyframes for existing Objects** #### None **None** does not attempt to match existing Grid Studio objects. The FBX structure is imported as new objects. #### Merge by Name **Merge by Name** compares the names of FBX objects with existing Grid Studio objects. If the name matches, the imported animation data is added to the existing object. If no matching object exists, a new object is created. {% hint style="warning" %} When using **Merge by Name**, use unique object names. If multiple Grid Studio objects share the same name, the match becomes ambiguous. For structured projects, **Merge by Path and Name** is usually the safer option. {% endhint %} #### Merge by Path and Name **Merge by Path and Name** compares both: * the object name * the object's position in the Parent / Child hierarchy A match is only made when the expected path and object name correspond. Grid Studio continues through the complete FBX hierarchy even if parts of the structure do not yet exist. Existing matching objects receive the imported animation, while missing objects or hierarchy levels are created automatically. This allows partially existing project structures to be completed by the import. #### Only add Keyframes for existing Objects **Only add Keyframes for existing Objects** uses the same Path-and-Name matching logic, but does not create missing objects. Grid Studio continues through the complete FBX hierarchy: * matching objects receive the imported animation * unmatched objects are skipped * no new objects are created This is useful when the FBX should only provide animation for an already prepared Grid Studio structure. #### Existing Mesh Objects When an existing Grid Studio object is matched during a merge, its Mesh is **not** replaced or updated. FBX Mesh geometry is imported only when a new object is created. Merging is therefore used to apply supported animation and transform data to existing objects without changing their existing object type or Mesh. *** ## Importing Animation The **Animation** option controls whether animation data from the FBX should be imported. #### Animation Off Disable **Animation** when only the FBX objects, hierarchy, Cameras, or Meshes should be imported. The selected Merge settings still apply to the object structure. If the import creates a new Timeline, the Timeline is still generated but contains no animation data. #### Animation On Enable **Animation** to import the FBX animation together with the object structure. The **Animation Type** determines how the imported animation is stored in Grid Studio. Available options are: * **Keyframes** * **Recording** *** ## Animation Type: Keyframes **Keyframes** imports the FBX animation as regular editable Grid Studio Parameter Keyframes. The resulting structure behaves like a normal Parameter Layer: * objects appear as sub-layers * animated Parameters appear below the objects * individual Keys can be viewed and edited This is the appropriate option when the imported animation should be manually adjusted inside Grid Studio. *** ## Animation Type: Recording **Recording** imports the animation into the same optimized data format used by Grid Studio Timeline recordings. The imported objects receive normal Recording Blocks inside the Parameter Layer. This format is optimized for efficient playback and is useful when the animation does not need to be edited as thousands of individual Keys. If required, the Recording data can later be converted using: **Convert all recordings to keys** For more information about the optimized Recording format, see the **Timeline Recording & Export Guide**. *** ## Animation Timing FBX animation import is not limited by the current Grid Studio **Project FPS**. Imported animation Keys are positioned using their timing in milliseconds. This allows the original animation timing to be placed on the Timeline independently from the current Project frame rate. *** ## Timeline Range The current Timeline Start Time and End Time do not limit where imported Keys can be placed. FBX animation can therefore be imported outside the currently configured active Timeline range. For example, animation can be imported at `01:00:00` even if the Timeline currently only displays or plays a much shorter range. After importing, adjust the Timeline range if required to make the complete imported animation available for playback and navigation. *** ## Importing into Existing Animation Importing into a Parameter Layer that already contains data does not automatically replace or trim existing Blocks. If imported animation occupies the same time range as an existing Block, both Blocks can temporarily exist at the same Timeline position. {% hint style="info" %} Overlapping imported and existing Blocks should generally be avoided. However, this behavior can be useful when adding or splicing new animation onto an existing sequence. {% endhint %} For example: 1. Import the additional FBX animation. 2. Move the imported Block to the desired position. 3. Trim the previous Block so that it ends where the imported animation should begin. Grid Studio does not automatically shorten the existing Block when new data is imported. *** ## Before a Large Import FBX import can create or modify many objects, hierarchy levels, and animation tracks in a single operation. {% hint style="warning" %} FBX imports cannot be undone using **CTRL + Z**. Save the project before performing a large import, especially when using: * **Merge by Name** * **Merge by Path and Name** * imports into existing Parameter Layers * large FBX hierarchies If the resulting matching or imported structure is not correct, the saved project provides a clean state to return to. {% endhint %}