What’s New

The latest version of the Alias Engine is v4.1.2.

v4.1.2

Release highlights

Improve error handling on Alias start up
Improve Alias API timeout handling

v4.1.1

Release highlights

New publish mode “Export Selection”
New publish option to choose publish mode

New Features

The Alias publish plugin “Publish to Flow Production Tracking” has a new Publish Mode option:

The “Default” publish mode will publish the working file as is, as it did before introducing the Publish Mode option, there is no change in behavior.

The “Export Selection” publish mode will publish only the selected objects in the Alias scene.

Note

The working file will not be changed. This means that the published file will differ from the corresponding working file version.

Warning

The “Export Selection” publish mode is not supported with Background Publishing. You must turn off the Background Processing setting in your configuration to use this publish mode. Refer to this documentation on how to turn off this setting.

By default, the “Default” publish mode is selected. To change the default publish mode, you can modify your configuration file tk-multi-publish2.yml, for example:

settings.tk-multi-publish2.alias.asset_step:
    publish_plugins:
    - name: Publish to Flow Production Tracking
        hook: "{self}/publish_file.py:{engine}/tk-multi-publish2/basic/publish_session.py"
        settings:
        Publish Template: alias_asset_publish
        Publish Mode: Export Selection

v4.0.1

Release highlights

Fix Alias Engine restart after Alias application exits unexpectedly

v4.0.0

This documentation explains the new features in the Alias Engine v4.0.0 compared to v3.3.2.

Release highlights

Improved performance overall for Alias 2024.0 and later
Improved Data Validation validation and fix operations
Improved communication and error handling with Alias

Dependencies

Data Validation App: tk-multi-data-validation v0.3.1
- Required for full performance improvements
- Recommneded to use the new option to turn off the app auto-refresh feature for best performance. Particularly when auto-refresh is on while switching between files (e.g. opening or importing a new file) will degrade performance.
Alias Framework: tk-framework-alias v2.0.0
- Required for full performance improvements
- Required for Alias Plugin and Python API updates

New Features

New Alias APIs are listed separately.

AliasPy

Added request_context_manager() context manager to improve performance of API calls:

Use the context manager to execute multiple API calls at once and retrieve the result:

# Wrap the API calls to create layers using the request context manager
with engine.alias_py.request_context_manager() as manager:
   for i in range (100):
      layer_name = f"Layer{i}"
      # This API call will be deferred until the context manager exits
      engine.alias_py.create_layer(layer_name)

# The context manager now on exiting the above code scope will send all
# API calls in a single event, instead of 100 individual events

# The result will be stored in the manager object `result` property, and it
# will be a list of values returned from the API calls, in the order that the
# API calls were made.
for result in manager.result:
   print(result)

See more details on how to use the context manager in the Alias Python API documentation.

AliasPyDagNode

Added is_template() function to check if a node is a template node. Replaces AliasPyTraverseDag.is_node_template method.

Added is_instance() function to check if a node is instanced. Replaces AliasPyTraverseDag.is_instance method.

Added has_zero_transform() function to check if a node has a zero transform. Replaces AliasPyTraverseDag.node_has_non_zero_transform method.

Added has_non_origin_pivot() function to check if a node has pivots at the origin. Replaces AliasPyTraverseDag.has_non_origin_pivot method.

Configuration

Added configuration setting data_validation_max_error_count to set the maximum number of errors to display in the data validation dialog. If the number of errors exceeds this number, then individual error items will not be retrieved and displayed, and only the number of errors will be shown. Lowering this number can improve Data Validation App performance. The default value is 500. This configuration setting can be found in the Alias Engine info.yml file, and can be modified in the tk-alias.yml configuration file.

Removed

Removed class AliasPyTraverseDag
- Attribute will no longer be available from the engine AliasEngine.alias_py.py_traverse_dag
Removed parameter check_exists from the following AliasPyDAgNode methods:
- get_instanced_node()
- get_nodes_with_construction_history()
- get_nodes_with_non_zero_transform()
- get_nodes_with_non_origin_pivot()
- get_nodes_with_unused_curves_on_surface()

This affects the AliasEngine.alias_py.py_dag_node attribute; for example:

# This method no longer takes the key-word parameter `check_exists`
nodes = engine.alias_py.get_nodes_with_non_zero_transform(check_exists=True)

# Should now be called without the `check_exists` parameter
nodes = engine.alias_py.get_nodes_with_non_zero_transform()

Removed parameter check_exists from function AliasPyLayer.get_symmetric_layers()
- This affects the AliasEngine.alias_py.py_layer attribute.
Removed parameter skip_shaders from function AliasPyPickList.pick_nodes_assigned_to_shaders
- This affects the AliasEngine.alias_py.py_pick_list attribute.

v3.0.0

This documentation explains the new features in the Alias Engine v3.0.0 compared to v2.2.1.

Porting to tk-alias v3.x.x from v2.x.x

Starting in tk-alias v3.0.0, the Toolkit Framework for Alias tk-framework-alias is required. The framework now manages the Alias Plugin and Alias Python API module files for all the supported Alias versions. Starting in Toolkit configs v1.6.0, the tk-framework-alias is included.

Accessing the API with the Alias engine in v2.x.x

In tk-alias v2.x.x the Alias Python API can be accessed directly by importing the alias_api module:

import alias_api

Accessing the API with the Alias engine in v3.x.x

In v3.x.x it is still possible to import the alias_api module:

import alias_api

Note: This requires the Alias Engine to be bootstrapped and started (e.g. launching Alias from Flow Production Track Desktop will do this). If you are manually bootstrapping the Alias Engine (without Flow Production Tracking Desktop), refer to how the framework bootsraps. and starts the engine.

To maintain future compatibility, we strongly encouraged accessing the Alias Python API through the tk-alias engine property alias_py:

import sgtk

# Get the Alias engine instance.
tk_alias_engine = sgtk.platform.current_engine()

# Access the Alias Python API through the engine property `alias_py`
# Remember that engine must have been started for alias_py property to be available
alias_api = tk_alias_engine.alias_py

Accessing the API without the Alias engine

The Alias Engine does not provide access to the Alias Python API when the engine is not running. Without the engine running, the additional AliasPy modules are not available. If it is absolutely necessary to use the Alias Python API without the tk-alias engine running, and without an active Alias session(e.g. headless mode, called OpenModel), you will need to:

Add the alias_api_om.pyd file path to your PYTHONPATH

_This is necessary for import to find the Alias Python API module._
Add the Alias install bin directory to your system environment PATH

_This is necessary to find the Alias DLL files that the Alias Python API requires._

Starting in tk-alias v3.0.0, the Alias Python API files are no longer included in the engine itself, instead they are managed by tk-framework-alias, and can be found here.

Here are steps to access the Alias Python API module for OpenModel (e.g. headless mode without an Alias session running):

Open a Windows Command Prompt and ensure that the Alias DLL install path is in your system environment PATH. If you have multiple installs of Alias, the version of Alias you want to use must appear first (in this example, it would be Alias 2025.0). You can check the PATH value by seeing the output of running the Windows set command. You can prepend the Alias install path to your PATH with:
set PATH=C:\Program Files\Autodesk\AliasAutoStudio2025.0\bin;%PATH%
NOTE: This only works for Python <= 3.9. For Python 3.9 and newer, you will need to add the Alias DLL install path from the Python interpreter. Keep following for instructions for Python 3.9.
Start a Python interpreter. We will use Python 3.7 for this example:
"C:\Program Files\Python37\python.exe"
NOTE: you may need to change the above path to the python.exe you want to use.

NOTE: For Python 3.9, now add the Alias DLL install path for python to find it:
import os os.add_dll_directory(alias_dll_directory)

Add the path to the Alias Python API module for OpenModel (alias_api_om.pyd) to your PYTHONPATH. We will use the API for Alias 2025.0, and Python 3.7 since we are running a Python 3.7 interpeter:

import sys
sys.path.insert(0, "C:\\Users\\<insert_username>\\AppData\\Roaming\\Shotgun\\bundle_cache\\app_store\\tk-framework-    alias\\v1.4.0\\dist\\Alias\\python3.7\\2025.0")

NOTE: you will need to replace <insert_username> with your username, and make sure this is the correct path to the alias_api_om.pyd file.

Optionally, the path to the api could have also been set before starting the interpreter from the Windows Command Prompt:

set PYTHONPATH=C:\Users\my_username\AppData\Roaming\Shotgun\bundle_cache\app_store\tk-framework-alias\v1.4.0\dist\Alias\python3.7\2025.0;%PYTHONPATH%

If you do not want to hard code the Alias Python API path C:\\Users\\my_username\\AppData\\Roaming\\Shotgun\\bundle_cache\\app_store\\tk-framework-alias\\v1.4.0\\dist\\Alias\\python3.7\\2025.0, and you have access to the Toolkit sgtk module and have your Toolkit context, you can programmatically find the path to the api with this function:

def setup_alias_env(
        ctx,
        alias_version="2024.0",
        alias_dll_directory="C:\\Program Files\\Autodesk\\AliasAutoStudio2024.0\\bin",
):
    import os
    import sys
    import sgtk

    env = sgtk.platform.engine.get_environment_from_context(ctx.sgtk, ctx)
    desc = env.get_engine_descriptor('tk-alias')

    # Get the framework version from the tk-alias engine descriptor
    framework_and_version = None
    for framework in desc.get_required_frameworks():
        if framework.get("name") == "tk-framework-alias":
            name_parts = [framework["name"]]
            if "version" in framework:
                name_parts.append(framework["version"])
            framework_and_version = "_".join(name_parts)
            break

    if framework_and_version is None:
        raise Exception("Failed to find location for tk-framework-alias")

    # Get the path to the framework
    framework_desc = env.get_framework_descriptor(framework_and_version)
    framework_path = framework_desc.get_path()

    # Get the API path within the framework, for the Python and Alias version
    api_path = os.path.join(
        framework_path,
        "dist",
        "Alias",
        f"python{sys.version_info.major}.{sys.version_info.minor}",
        alias_version,
    )
    if not os.path.exists(api_path):
        raise Exception(f"Alias Python API module not found: {api_path}")

    # Add the path to the api so that we can import the module
    sys.path.insert(0, api_path)

    # For Python > 3.7, we need to add the Alias bin dir to the dll directories to find the correct Alias DLLs to load the api module
    # For Python <= 3.7 the Alias bin dir should have been added to the system environment PATH before executing this script
    if hasattr(os, "add_dll_directory"):
        os.add_dll_directory(alias_dll_directory)

Now you are ready to import the Alias Python API:
From a command line, without Alias running, we are operating in OpenModel mode (e.g. no GUI), so we need to import the OpenModel API module:
import alias_api_om # Print help for the module help(alias_api_om) # Print the api module file location print(alias_api_om.__file__) # Execute a basic api command status = alias_api_om.initialize_universe() # If successful, you should see a return of `0` print("Alias universe initialized", status)
NOTE: when running with Alias, we are operating in OpenAlias (e.g. with a GUI), in this case we could import the API as import alias_api

Troubleshooting

Alias Python API module not found:
ModuleNotFoundError: No module named 'alias_api_om'
This indicates that the alias_api_om.pyd file could not be found. Check that you have set your PYTHONPATH environment variable or sys.path to include the path to the alias_api_om.pyd file.
Alias DLL import error:
ImportError: DLL load failed while importing alias_api_om: The specified module could not be found.
This indicates that the necessary Alias DLLs could not be found. Check that you have set your PATH environment variable (for Python <= 3.7) such that the correct Alias install path appears first, or this path was added using os.add_dll_directory (for Python > 3.7)
ModuleNotFoundError: No module named ‘tk_framework_alias_utils’ (or ‘tk_framework_alias’)
This means you are attempting to import the tk_framework_alias python module. To import the Alias Python API module without the Alias engine, we do not need to import tk_framework_alias module to get the Alias Python API. Instead, follow the steps above to add the direct path to the Alias Python API module instead of tk_framework_alias, in order to import the api. You may import tk_framework_alias to access the api, but it has additional Python package dependencies that you are on your own to ensure are installed.

Ensure that the path to the tk_framework_alias python module is not in your PYTHONPATH. The tk_framework_alias python module path may look something like: C:\Users\username\AppData\Roaming\Shotgun\bundle_cache\app_store\tk-framework-alias\v1.4.0\python. You can check your path with:
set PYTHONPATH
, and update it to remove the tk_framework_alias path, if it is present:
set PYTHONPATH=<new_path_without_tk_framework_alias>

Module Changes

AliasPy

NOTE: the AliasPy modules are only available with the Alias Engine and when it has been started.

In v2.x.x the AliasPy utility modules can be accessed directly by importing from the alias_py module:

import alias_py.utils
import alias_py.dag_node
import alias_py.layer

In v3.x.x this is no longer possible. The AliasPy utility modules must be accessed through the Alias engine property alias_py:

import sgtk
tk_alias_engine = sgtk.platform.current_engine()

alias_api = tk_alias_engine.alias_py

# Previous `alias_py` attributes arenow accessed using `engine.alias_py.py_<attr_name>`
utils_module = alias_api.py_utils
dag_node_module = alias_api.py_dag_node
layer_module = alias_api.py_layer

API Changes

AlStatusCode Enum

In v2.x.x the Alias Python API status code numerical values can be retrieved by:

if int(alias_api.AlStatusCode.Success) == 0:
    print("Success!")

In v3.x.x this code must be updated to use the value attribute to retrieve the numerical value:

if alias_api.AlStatusCode.Success.value == 0:
    print("Success!")

# Or check the status by name now
if alias_api.AlStatusCode.Success.name == "Success":
    print("Success!")