mari.session

A collection of tools for importing/exporting live session data to/from Mari.

Description

Important:
Requires Mari2.6

This package provides importing/exporting functionality at three levels of abstraction. Which level makes the most sense for a given situation will depend on the amount of defaulting or flexibility you need:

PySide UIs

Wrapper functions

Object-oriented API

The UIs are the quickest easiest way for end-users to access the importing/ exporting functionality. Three dialogs are provided, one for exporting, one for importing and one for importing selected channels. To access them you can either construct them directly via their constructors or you can call the wrapper functions that construct them for you.

The wrapper functions provide a very simple python interface to the importing/ exporting functionality. These will serve users who don’t need to do anything too tricky but basically just want to save and restore complete sessions.

See the “Exporting” and “Importing” subsections below for more info.

The Object-Oriented API is the lowest level interface to the import/export behavior. The OO class structure represents each type of item in Mari as its own object. So we have an object for the Project, GeoEntities, Channels, Layers, etc. They are hierarchically related and allow upward and downward traversal via the parent attribute and walk() method, respectively. All objects in the hierarchy inherit from a common base class, MariEntity, which provides a core set of functionality. The API is designed to keep the verbosity of the tools that use it to a minimum. Thus there are lots of helper methods and properties that make writing client code very easy and efficient. See the “Using the Object-Oriented API” section below for more info.

Exporting

You can export all channel/layer data for every object in the session. The system handles advanced Mari2 features like shared layers and channel layers.

To perform a basic export of a Mari session execute the following:

>>> mari.session.exportSession(exportDir)

After the export is complete, the resulting directory structure will look like this:

>>> exportDir/projectName/
>>>                         objects/
>>>                             object1Name
>>>                             object2Name
>>>                             object3Name
>>>                             ...
>>>                         textures/
>>>                             texture1Name
>>>                             texture2Name
>>>                             texture3Name
>>>                             ...
>>>                         projectName.msf

You can also export using the UI export dialog:

>>> mari.session.exportSession()

or

>>> mari.session.ExportDialog().exec_()

Importing

You can import the data from a session file that was exported by the exportSession() function. It will attempt to use existing geoEntities in the current session with the same names as the geoEntities recorded in the exported session file, but if any of the geoEntities don’t exist, it will create them by loading the appropriate geometry.

To import a session that was exported by exportSession(), simply execute the following:
>>> mari.session.importSession("/path/to/exported/MariSessionFile/file.msf")
You can also import using the UI import dialog:
>>> mari.session.importSession()
or
>>> mari.session.ImportDialog().exec_()

Using the Object-Oriented API

To use the API, you’ll most often want to start by getting an instance of a high level MariEntity (all objects inherit from the MariEntity base class) like a Project or GeoEntity.

To get a Project instance that represents the currently open Mari project:
>>> from mari.session import Project
>>> currentProject = Project.fromSession()
Similarly you can get the currently selected GeoEntity:
>>> from mari.session import GeoEntity
>>> selectedGeo = GeoEntity.fromSelection()
You can also obtain a Project instance from an exported msf (Mari Session File) file:
>>> from mari.session import Project
>>> exportedProject = Project.fromMSF('/path/to/MariSessionFile/file.msf')
Once you have an instance of a Mari entity (such as a Project or GeoEntity) you can access all the features of the API. You can traverse the hierarchy of the Mari Project, up or down, from any MariEntity by calling the parent property (to move up), or by calling walk() (to move down) through the object tree. All MariEntities have the following properties:

name
The name of the entity in Mari.

fullName
A “full” name for the entity, generated by concatenating its parents’ names, recursively.

dependencies
A list of entities this entity depends on.

mariObject
A reference to the actual Mari object represented by this entity, if it exists in the currently open project.

parentChannel
A convenience property to directly return the channel to which this entity belongs.

parentGeoEntity
A convenience property to directly return the geo entity to which this entity belongs.

parentProject
A convenience property to directly return the project to which this entity belongs.

treeDiagram
A convenience property that returns a string representation of the object hierarchy from this entity down through its children.

uid
This property is mainly for use internally in the API but can be useful for identifying a MariEntity when two entities may have the same name.

The make() method

The make() method on a MariEntity is the way we “import” data into the active Mari project. When you call make() on a Project object, it iterates over each of its GeoEntities and creates them in the active session (if they don’t already exist). After the GeoEntities have been created, the make() process proceeds to build the channels, layers, etc. that belong to those GeoEntities, recursively until the active Mari project reflects the Project object’s hierarchy. As part of this process, images that are referenced in the Project object’s hierarchy are imported into ImageSets for the appropriate layers. Calling make() on a Project that was constructed from an exported msf file will have the effect of importing that msf file back into the active Mari session.

GeoEntity.copyChannels()

Sometimes it is desired to be able to export channels from one geo entity in one Mari session and import it into a completely different geo entity in a separate Mari session. In order to support this kind of functionality, the GeoEntity class provides a copyChannels() method, which can clone channels from one GeoEntity object into another GeoEntity object. Once the channels have been cloned, all you have to do is call make() on the GeoEntity object that received the new channels and voila! The new channels have been imported.

mari.session.exportSession(exportDir=None, geoEntities=None, geoVersions=None, channels=None, geoPatches=None, shaders=None, images=None, copyObjectFiles=False, lights=None, cameras=None, projectors=None, name=None, template=False, finishedCallback=<function <lambda>>)

Export the current Mari session in a format that can be shared.

The export process will yield a directory structure like this:

>>> exportDir/projectName/
>>>                     objects/
>>>                         object1Name
>>>                         object2Name
>>>                         object3Name
>>>                         ...
>>>                     textures/
>>>                         texture1Name
>>>                         texture2Name
>>>                         texture3Name
>>>                         ...
>>>                     images/
>>>                         image1Name
>>>                         image2Name
>>>                         image3Name
>>>                         ...
>>>                     projectors/
>>>                         projector1Name
>>>                         projector2Name
>>>                         projector3Name
>>>                         ...
>>>                     projectName.msf

EXPORT PARAMETERS:: None - exports everything. [] - exports nothing.

Parameters:

exportDir (str) – The full path of the directory in which to write the files. Defaults to None
geoEntities (list of mari.GeoEntity|mari.session.GeoEntity) – A list of geo entities to include in the export. By default all geo entities are included. Defaults to None
channels (list of mari.Channel|mari.session.Channel) – A list of channels to include in the export. By default all channels are included. Defaults to None
geoPatches (list of mari.GeoPatch) – A list of geo patches to include in the export. By default all geo patches are included. Defaults to None
shaders (list of mari.Shader|mari.session.Shader) – A list of shaders to include in the dict. By default all shaders are included. Defaults to None
images (list of mari.Image|mari.session.Image) – A list of images to include in the dict. By default all images are included. Defaults to None
copyObjectFiles (bool) – Whether or not to copy object files. Defaults to False.
lights (list of mari.Light|mari.session.Light) – A list of lights to include in the dict. By default all lights are included. Defaults to None
cameras (list of mari.Camera|mari.session.Camera) – A list of scene cameras to include in the dict. By default all scene cameras are included. Defaults to None
projectors (list of mari.Projector|mari.session.Projector) – A list of projectors to include in the dict. By default all projectors are included. Defaults to None
name (str) – The name to give the .msf file and its folder. Defaults to None
template (bool) – Whether or not to export the project/session as a template, this decides whether or not to export textures for Paintable layers. Defaults to False.
finishedCallback (callable) – A callable that accepts a single mari.session.MariEntity object as an argument that is called when each of the Project’s descendant entities finishes being exported. Defaults to (lambda x: None)

Raises:

RuntimeError – No project was open when this function was called.
mari.session.MissingDependenciesError – The set of entities to export contains a dangling dependency.

mari.session.getRegisteredFunction(method=None)

Get the function registered to method provided.

Parameters:: method (basestring) – The name of the method to retrieve the function from. Defaults to None
Returns:: function – The function registered with the method.

mari.session.importChannels()

Display a dialog for importing channels from an exported msf file.

Raises:: RuntimeError – No project was open when this function was called.

mari.session.importNodeGraphs()

Display a dialog for importing node graphs from an exported msf file.

Raises:: RuntimeError – No project was open when this function was called.

mari.session.importSession(sessionFilePath=None, geoEntities=None, finishedCallback=<function <lambda>>)

Import data from an exported Mari session.

Parameters:

sessionFilePath (basestring) – The full path to an exported Mari session msf file. Defaults to None
geoEntities (mari.GeoEntity) – List of geoEntities to merge the data with. Defaults to None
finishedCallback (callable) – A callable that accepts a single mari.session.MariEntity object as an argument that is called when each of the Project’s descendent entities finishes being made. Defaults to (lambda x : None)

Raises:

mari.session.NoProjectOpenError – No project was open when this function was called.

mari.session.importShaders()

Display a dialog for importing shaders from an exported msf file.

Raises:: RuntimeError – No project was open when this function was called.

mari.session.registerFunction(method=None, callFunction=None)

Register a function with a mari.session method.

Gives users the ability to register a function with a mari.session method to be called at specific times when exporting/importing.

Note that the finishedCallback function is ONLY used when export session is called via the GUI. Using python, you can directly pass in the callback function using the named parameter “finishedCallback”. However, using the UI, there’s no way to do so and we call our hardcoded function to print some details about thefoundry export as well as call any function registered here.

Parameters:

method (basestring) –
The name of the method to register the function to. Defaults to None .. method:: - copyFile

- preExport

- postExport

- preImport

- postImport

- finishedCallback
callFunction (function) – The function to call.Defaults to None

Returns:

bool – True if successful, False otherwise.

Provides exception definitions for use by the mari.session package.

This module provides the following exceptions:

MariSessionError - Base exception class for errors specific to the mari.session package.
MissingDependenciesError - Exception for cases when required dependencies are missing.
NoProjectOpenError - Exception for cases where no project is open but one is required to be.

exception mari.session.exceptions.InTerminalModeError

Bases: MariSessionError

Exception for cases where Mari is being run in Terminal mode but is required to be in GUI mode.

exception mari.session.exceptions.InaccessiblePathError(path)

Bases: MariSessionError

Exception for when path is inaccessible.

__init__(path)

Initialize this instance.

Parameters:: path (basestring) – The path which is inaccessible.

exception mari.session.exceptions.MariSessionError

Bases: Exception

Base exception class for errors specific to the mari.session package.

exception mari.session.exceptions.MissingDependenciesError(dependencies)

Bases: MariSessionError

Exception for cases when required dependencies are missing.

__init__(dependencies): Initialize this instance.

property dependencies

(dict) The missing dependencies that caused this error to be raised.

The keys of the returned dict are mari.session.MariEntitys and the values are lists of the mari.session.MariEntitys they depend on.

exception mari.session.exceptions.NoPathProvidedError

Bases: MariSessionError

Exception for when user does not provide a path.

exception mari.session.exceptions.NoProjectOpenError

Bases: MariSessionError

Exception for cases where no project is open but one is required to be.

exception mari.session.exceptions.ProcessCanceledError

Bases: MariSessionError

Exception for when user cancels process.

Session Preferences class for Mari.

class mari.session.preferences.Preferences

Bases: QObject

Class for handling loading/saving preferences.

This class is instantiated when Mari opens and can be accessed via mari.session.Preferences.

property EXPORT_BYTE_IMG_TYPE

property EXPORT_FLOAT_IMG_TYPE

property EXPORT_HALF_IMG_TYPE

property IMAGES_FOLDER

property NODEGRAPH_FOLDER

property OBJECTS_FOLDER

property PROJECTORS_FOLDER

property TEXTURES_FOLDER

__init__(): Initialize this instance.

preferenceChanged

staticMetaObject = PySide6.QtCore.QMetaObject("Preferences" inherits "QObject": Methods: #5 type=Signal, signature=preferenceChanged(PyObject,PyObject), parameters=PyObject, PyObject )

Provides an export/import API for Mari sessions.

mari.session.types

Classes

MariEntity: Abstract base class representation of an entity in Mari.
Project: Session representation of a Mari project.
GeoEntity: Session representation of a Mari geo entity.
Channel: Session representation of a Mari channel.
LayerStack: Session representation of a Mari layer stack.
Layer: Session representation of a Mari layer.
ImageSet: Session representation of a Mari image set.
Image: Session representation of a Mari image.
Shader: Session representation of a Mari shader.
Light: Session representation of a Mari Light.
Projector: Session representation of a Mari Projector.

Description

This module provides an object-oriented API for importing/exporting live Mari session data. The OO classes are structured to directly reflect the object structure of a Mari project. Each class represents a type of object in Mari. So we have classes for the Project, GeoEntities, Channels, Layers, etc, which are all hierarchically related. All objects in the hierarchy inherit from a common base class, MariEntity, which provides a core set of functionality common to all mari entities.

To use the API, you’ll most often want to start by getting an instance of a high level MariEntity like a Project or GeoEntity.

To get a Project instance that represents the currently open Mari project:

>>> from mari.session import Project
>>> currentProject = Project.fromSession()

Similarly you can get the currently selected GeoEntity:

>>> from mari.session import GeoEntity
>>> selectedGeo = GeoEntity.fromSelection()

You can also obtain a Project instance from an exported msf file:

>>> from mari.session import Project
>>> exportedProject = Project.fromMSF('/path/to/MariSessionFile/file.msf')

Once you have an instance of a Mari entity (such as a Project or GeoEntity) you can access all the features of the API. You can traverse the hierarchy of the Mari Project, up or down, from any MariEntity by calling the parent property (to move up), or by calling walk() (to move down) through the object tree. All MariEntities have the following properties:

name
The name of the entity in Mari.

fullName
A “full” name for the entity, generated by concatenating its parents’ names, recursively.

dependencies
A list of entities this entity depends on.

mariObject
A reference to the actual Mari object represented by this entity, if it exists in the currently open project.

parentChannel
A convenience property to directly return the channel to which this entity belongs.

parentGeoEntity
A convenience property to directly return the geo entity to which this entity belongs.

parentProject
A convenience property to directly return the project to which this entity belongs.

treeDiagram
A convenience property that returns a string representation of the object hierarchy from this entity down through its children.

uid
This property is mainly for use internally in the API but can be useful for identifying a MariEntity when two entities may have the same name.

uuid
This property is mainly for use internally in the API but can be useful for identifying a MariEntity when two entities may have the same name.

metadata
This contains the Mari metadata on this entity.

The make() method

The make() method on a MariEntity is the way we “import” data into the active Mari project. When you call make() on a Project object, it iterates over each of its GeoEntities and creates them in the active session (if they don’t already exist). After the GeoEntities have been created, the make() process proceeds to build the channels, layers, etc. that belong to those GeoEntities, recursively until the active Mari project reflects the Project object’s hierarchy. As part of this process, images that are referenced in the Project object’s hierarchy are imported into ImageSets for the appropriate layers. Calling make() on a Project that was constructed from an exported msf file will have the effect of importing that msf file back into the active Mari session.

GeoEntity.copyChannels()

Sometimes it is desired to be able to export channels from one geo entity in one Mari session and import it into a completely different geo entity in a separate Mari session. In order to support this kind of functionality, the GeoEntity class provides a copyChannels() method, which can clone channels from one GeoEntity object into another GeoEntity object. Once the channels have been cloned, all you have to do is call make() on the GeoEntity object that received the new channels and voila! The new channels have been imported.

Defines UIs for importing/exporting sessioned Mari data.

mari.session.ui

Classes

ChannelDialog A dialog for importing specific channels from a msf file.

ExportDialog A dialog for exporting Mari session data.

ImportDialog A dialog for importing Mari session data.

ShaderDialog A dialog for importing specific shaders from a msf file.

Examples

To bring up the channel dialog:

>>> mari.session.ui.ChannelDialog().exec_()

To bring up the export dialog:

>>> mari.session.ui.ExportDialog().exec_()

To bring up the import dialog:

>>> mari.session.ui.ImportDialog().exec_()

To bring up the shader dialog:

>>> mari.session.ui.ShaderDialog().exec_()

Utils session types package.