New Project Dialog

The New Project dialog is described below with functions for how to access it. A list of the controls on the dialog box can be found in the table below.

What It Does

The New Project dialog lets you select geometry and various options for a new Mari project. Use the Path control to select an .obj, .ptx, .abc, or .fbx file you want to use in the project.

Resize the dialog box to display long filenames or select multiple files to display more than one geometry, if they are of the same file type. Mari checks the model for any errors that might prevent it from processing, for example, whether UVs overlap or touch border edges. A Mesh Sanity Check dialog displays any warnings or errors. (Errors cancel opening the model, but you can continue with warnings.)

Depending on the size and complexity of textures, it can take several minutes the first time you load them into a Mari project. Once saved, however, the project should open quickly in future.

How to Access It

Menubar | File > New

Keyboard | Ctrl/Cmd+N

Projects tab | New button

Projects tab | Right-click > New

Toolbar |

New Project Dialog Box Fields



What it does

Opens this dialog box


Project Name

text field

Lets you specify the name of the project.


This is for you to identify the project only (this is not a filename).



text field, dropdown, button

Opens .obj, .ptx, .abc, or .fbx files. Dropdown lists the last 10 opened.

Once you select a file, the Mesh options appear under the root Path.

Pick Mesh dialog

Select by either typing the Path, selecting from the dropdown of the last 10 files selected, or clicking the button to browse to a file.

Mesh options | Mapping Scheme


If there is a UV map available, and you would like to use it, select UV if available, Ptex
. If you prefer to use Ptex, select Force Ptex. This option loads the selected geometry and replaces the existing UV map with a Ptex map.


Only available when choosing .obj, .abc, or .fbx files in the Path.

Mesh options | Selection Groups


Selection groups have two options, to either:

Create From Face Groups - this is the default behavior and allows the use of selection groups in Mari.

Don’t Create - if you choose not to create a selection group, Mari does not create any from the file.


Only available when choosing .obj files in the Path.

Mesh options | Multiple Geometries Per Object


If your .obj consists of multiple geometries, you have the option to Merge Geometries Into One, which is the default behavior, or Create Separate Geometries (Ptex Only). If you select Merge Geometries Into One, Mari combines the individual geometries into a single geometry, while selecting Create Separate Geometries (Ptex Only) creates individual geometries.


Only available when choosing .obj files in the Path.

Even if you select Create Separate Geometries (Ptex Only), Mari only displays a single geometry on the canvas. However, when you export a channel you have the option to export individual .ptx files for each geometry.

Mesh options | Start Frame and End Frame

text field

Set the frame range from the source file to import.


Only available when you are loading an animated sequence using the .obj, .abc, or .fbx formats.

Mesh options | Single Frame


Sets the other fields to only import the first frame from the animation in the object file.


Only available when you are loading an animated sequence using the .obj, .abc, or .fbx formats.

Mesh options | All Frames


Sets the other fields to import the entire animation from the object file.


Only available when you are loading an animated sequence using the .obj, .abc, or .fbx formats.

Mesh options | Merge Type


For Ptex files, there are two choices for the geometry mesh options:

Separate Meshes - creates only one object with one geometry.

Single Mesh - creates only one object, but has multiple geometries within it.


Only available when choosing .ptx files in the Path.

The option to Separate
Geometry In One Object
is essentially the inverse of the Ptex channel export process, and allows project reconstruction.

Mesh options | Merge Type dropdown

Choose whether to merge selected items from the objecthierarchy tree as:

Single Mesh - merges selected geometry into one single mesh in a GeoEntity.

Note:  Note that this implies that the information about the original geometries cannot be accessed once the merge is done.

Just Merge Nodes - merges selected geometry into one GeoEntity while retaining the metadata and mesh information about the original individual geometries.

Note:  This information can only be accessed by more technical artists using the C API. see, Software API Overview.


Only available when choosing .abc or .fbx files in the Path.

Mesh options |Merge Selection Groups


You can choose to Merge selection groups with the same name or choose the Do not merge selection groups option.


For more information on selection groups, see Selection Groups.

Mesh options |Take

dropdown, information

If an object has been exported as part of an .fbx file with animation takes, the takes are shown in the dropdown menu. Otherwise, information regarding the only take available is shown.


Only available when choosing .fbx files in the file browser. When adding an object with animation takes, the take can only be selected on import and cannot be changed at a later point.

Mesh options | Scene


In the object hierarchy, shows all the geometries or meshes, cameras, and groups that are part of the selected Alembic file.

Expanding the parent row, reveals the child geometries beneath it.


Only available when choosing .abc or .fbx files in the Path.

Mesh options | Merge


Select the checkbox to determine if a geometry is to be merged with another on project creation.


Only available when choosing .abc or .fbx files in the Path.

For more information on merging Alembic or FBX geometry, see Creating a New Project with Alembic and FBX Files

Mesh options | Frame Offset

text field

Set by how many frames to offset the loading of an animated object. You can specify a frame range, or simply a number of frames.


Only available when choosing .abc files in the Path.



Root Path

dropdown, button

Displays the root path for the project. This is where Mari looks for any existing textures to import as it creates the channels.

Choose Base Path dialog

This is the value that Mari substitutes for $PATH in the import templates in the bottom list.



Scans the Root Path for any existing texture files.


After scanning the Root Path, you should always set the Size of the texture files manually. The default values Mari sets may not be correct as channels can contain many different patch sizes.



Selects a Mari channel preset template from the list of available shaders.


General, Principled BRDF - Metallic - Games, Principled BRDF - Metallic - VFX, Principled BRDF - Non Metallic - Games, Principled BRDF - Non Metallic - VFX, Unreal - Metallic - Games, Unreal - Metallic - VFX, Unreal - Non-Metallic - Games, Unreal - Non-Metallic - VFX, VRayMtl - VFX



Specifies a channel template to control the format of the filenames when Mari looks for existing textures on disk.


For more information about channel templates, see Defining Custom Channel Templates, Reviewing the Custom Channel Template File Format, and Example File: DefaultTemplates.mtt.


text field

Specifies the filename prefix for existing texture files, if applicable.





When enabled, creates a shader and connects channels to the shader on project creation.


Most presets contain enabled channels by default.



Imports existing textures into the channel after creating it.





Specifies the name of the channel to create. Mari sets a default value, but you can change this.


For example, color, specRough, dispFine, dispBroad, colorDetail, colorDetailMask.



Specifies the patch size for the new channel. Mari sets a default value, but you can change this.


256x256, 512x512, 1024x1024, 2048x2048, 4096x4096, 8192x8192, 16384x16384, 32768x32768



The colorspace in which the colors within your project are interpreted. Either select from the shipped config files or allow Mari to set an Automatic colorspace.


You can change these settings within the project after project creation, if necessary.

Tip:  You can limit the number of colorspaces available to artists using the Python API registerConfigUiAllowlist() function or the MARI_COLORSPACE_OCIO_UI_ALLOWLIST environment variable. See Help > SDK > Python > Documentation from Mari's UI menus or Environment Variables That Mari Recognizes for more details.



When Colorspace is set to Automatic, checking Scalar converts the resolved colorspace to scalar data.

Scalar data in Mari is used to define the properties of a texture such as bumpiness, roughness, or shininess.

See Color Data and Scalar Data for more information.

Note:  Automatically resolved 32-bit channels cannot be converted to scalar data. Only 8- and 16-bit channels are supported.


Scalar is disabled by default.

File Space


Specifies the file space used when generating vectors. Mari sets a default but you can change this.


Normal, Vector, Vector (flipped Y), or Normal (flipped Y)



Specifies the color to fill the new channel. Mari sets a default value, but you can change this.


Click the swatch to change the color.



Specifies the color depth size. Mari sets a default value, but you can change this.


8bit (Byte), 16bit (Half), or 32bit (Float).



Specifies the filename template used to pick existing textures to import into the channel. Mari sets a default value, but you can change this, or you can use the button to open a dialog allowing you to manually pick the files.


This option is ignored if the Import checkbox is disabled.


Opens a dialog box allowing you to pick the textures for Mari to import into the new channel.

Import Dialog



Indicates that Mari has not found any textures to import.


If there are textures to import, Mari displays the number of patches available.

Color Settings

Note:  All of the following Colorspace options can also be changed after project creation, if you decide you no longer want to use the colorspace setting that was chosen during project creation.

Color Management Enabled


Enables or disables the OpenColorIO color management.



OCIO Config


A list of either user-defined config files (Custom) or shipped OpenColorIO config files that handle colorspace.



Custom OCIO Config

text field, button

If you chose Custom for the OCIO Config file choice, specify the filepath to the config file.



Color Monitor


The default colorspace, which applies to thumbnails and UI elements.

Typically, this should be the same colorspace as you intend to use for the canvas.



Scalar Monitor dropdown

The default colorspace for all user interface elements which are displaying non-color managed (i.e. scalar) swatches, pickers, and thumbnails. (To understand the difference between color and scalar data in Mari, see Color Data and Scalar Data).

This preference does not affect the canvas and image viewers, however it is recommended to set this to match the scalar View Transform. (The active selection can be changed using the View Transform Toolbar .)


Color Picking (advanced and intermediate color management modes only)


The colorspace for all color pickers, swatches, and image viewers.



Working (advanced color management mode only) dropdown

Default for painting, lighting, applying filters, and similar operations.

Typically, you'll want to select the same linear-based colorspace as your 16/32-bit float channels to get accurate results.

Working (advanced mode only) dropdown


(advanced color management mode only)


Default for applying blending operations such as: a comp of the paint buffer and the current paint target, blending between layers, and combining inputs in a merge node.

Typically, you'll want to set this to Same as 8 bit Data to get the same results as painting prior to Mari 3.0, and to get less banding artifacts when painting 8-bit channels and images.


(advanced mode only)


8 bit Color


The default colorspace for 8-bit channels, and reading and writing image files with 8-bit data.



16-bit Integer Data


The default colorspace for 16-bit channels, and reading and writing image files with 16-bit data.



8/16-bit Scalar


The default colorspace for masks, heights, normals, depths and, generally, any non-color image with 8-bit or 16-bit data.



16/3-bit Float Data


The default colorspace for 16- and 32-bit (float) channels, and reading and writing image files with 16- and 32-bit, floating point data.







Specifies the shading model from one of the following:

Current Shader

Current Channel

Current Layer & Below

Current layer

Current Paint Target





Specifies the lighting on the main mesh. Mari comes with five default modes for lighting the model, and optional shadow control:

Flat - a flat, uniform, directionless light.

Basic - basic diffuse lighting without specular.

Basic with Shadows - basic lighting with diffuse lighting, as well as shadows.

Full - full lighting with diffuse and specular lighting.

Full with Shadows - full lighting with diffuse and specular lighting, as well as shadows.



Active Light Count

text field, slider

Specifies the number of active directional lights.



Environment Map

arrows, preview button, file browser, reset

Click the blank image space to choose an environment from the Mari Environment library. Clicking either of the arrow keys cycles backwards or forwards through the Mari Environment library, loading the image as it does.

Clicking the file browser opens the Open an Image dialog. Select an image of any of the file formats listed in the File of Type field.

You can also drag-and-drop an image from a file browser onto the blank image space to load the image as an environment light.


For more about the options in the dialog, refer to Open an Image Dialog.

Create New Project


Creates and opens the new project.





Cancels the new project creation.



Importing USD Files

USD is Pixar's extensible, layered scene description framework that offers scalable, collaborative, non-destructive workflows for VFX and animation production. Mari ships with a user friendly importer for bringing USD files directly into your project.

When loading in a USD file, you are offered specific settings within the Geometry tab. Options found in the Channels, Color Settings and Lighting tabs are the same as they would be when loading a .obj, .abc or .fbx file.

Note:   Mari can open  .usd, .usda, or.usdz files.

Use File > New to to open the New Project dialog, or Objects > Add Object to open the Add Objects dialog.  

In the New Project dialog, select a Path for the file by typing, using the dropdown to select from the last ten files, or clicking the browse button to open the Mesh Picker dialog.

Filtering USD Imports Using the Mesh Tree

Mari’s USD importer allows you to filter the scene by mesh and variant sets, before the import. 

The Mesh tree shows a hierarchical collection of all meshes contained within the incoming USD file.

Choose the meshes you want to import by toggling the checkmark next to the mesh prim name.

Right-click anywhere in the tree to open the context menu.

Selection options are:

  • Select All - Check all meshes in the tree for import.
  • Select None - Uncheck all meshes to exclude from import. This option is useful if you then want to select particular meshes.
  • Select by Expression - Use a simple expression to filter the meshes. This option lets you filter by path name without having to choose from the mesh tree.
    To include meshes, add prim paths separated by commas. For example: /room/table,/room/chairs
    To exclude meshes, prefix the prim path name with a !. For example:/room,!/room/cupboard
    Note: To exclude a mesh, you must first include its parent mesh.
    You can combine inclusion and exclusion as required.

All selections populate the Selected Items field. This is a non-editable field where you can check your import meshes list.

The context menu offers the following tree viewing options:

  • Expand All - Fully expand the mesh tree,
  • Collapse All - Collapse the mesh tree to the top-level prims.

Filtering USD Imports by Variant Sets

In USD, a Variant Set is a convenient way of managing alternate versions of models so you can choose which you prefer. USD supports two main types of variant sets: model variant sets and shading variant sets. Currently, Mari lets you load model variant sets only.

If there are any variant sets in the USD file, you must select your preferred variant from each set.  The New Project dialog is populated with all model variant sets with the name of each set and a dropdown to choose the preferred variant.

Additional USD Import Options

Refine the import using the following options.

Control Type Role
Merge Type dropdown Choose whether to merge the models:
Merge Models - merges all of your models into one object.
Keep Models Separate - imports all specified models as separate objects.
UV Set dropdown Specify which UV Set from your USD file to use in Mari.
Frame Numbers text field Specify which frame numbers to load.
Mapping Scheme dropdown Specify the Mapping Scheme, there are two options:

UV if available, Ptex otherwise - allows you to work with UV maps specified in the UV Set parameter.

Force Ptex - ignores any UV sets assigned to the model and uses Ptex instead.

For more information on Ptex, also known as Per-face Texturing, see Ptex.

Keep everything centered

button Toggle on to discard any transforms applied to your model and keep everything centered.

Conform to Mari Y as up

button When toggled on, Mari considers the Y axis in your project as up.

On by default.

Load Invisible Models

button When toggled on, meshes marked as invisible in the USD file are loaded into Mari. When off, invisible meshes are ignored.

Create Face Selection Group per Mesh

button Toggle on to create a selection group for each mesh in the project.
For more information on selection groups, see Selection Groups.