pytuflow.DAT.to_alembic

DAT.to_alembic(output_path, mesh_geometry='', vertex_colour=(), uv_projection_extent=(), location_ref=None, time_sample_frequency=1, time_sampling=0.041666666666666664, export_for='opengl')

Exports the mesh to an Alembic file for visualisation in compatible software.

Experimental Feature

Alembic export is an experimental feature and may not work for all formats and drivers. It may also be modified without warning in future releases. It requires the pyalembic library to be installed.

Parameters:

• output_path (Path | str) – The output file path for the Alembic file.

• mesh_geometry (str, optional) – The data type to use for the mesh geometry, e.g. "water level". If not provided, the mesh geometry will be used e.g. this will be the "Bed Elevation" for XMDF results.

• vertex_colour (Array[str], optional) –

  The provided data types will be exported into the mesh vertex colours. This allows a maximum of 3 data types only, one in the red channel, blue channel, and green channel. Vector types require 2 channels and should use a suffix with either "-x" or "-y" (e.g. "Vector Velocity-x" for the x vector component).

  The data types will be re-mapped to the 0-1 range for the colour channels by using the following formula
  packed_value = (value - value_min) / (value_max - value_min).
  The value_min and value_max are obtained using the minimum() and maximum() methods.
  An example usage would be ["Depth", "Vector Velocity-x", "Vector Velocity-y"] to pack depth into the red channel, velocity x into green, and velocity y into blue.

• uv_projection_extent (Array[float], optional) – The extent to use for UV projection of textures onto the mesh. The format is (min_x, min_y, max_x, max_y). If not provided, the mesh bounding box will be used except for TUFLOW HPC/Classic XMDF results which will use the model domain extent as defined in the .2dm. For HPC/Classic models, this matches the output grid setting Grid Output Origin == MODEL ORIGIN.

• location_ref (Mesh, optional) – The location reference to use when setting the geometry origin. By default, the mesh bounding box is used to set the geometry origin (it uses the centre of the bounding box). Another mesh result can be used to define the origin instead, which is useful when exporting multiple meshes that need to be aligned in 3D space.

• time_sample_frequency (int, optional) – The frequency in which to sample the time steps in the mesh file. A value of 1 means every time step will be exported, a value of 2 means every second time step will be exported, and so on. Default is 1.

• time_sampling (float, optional) – The time sampling interval in seconds. Default is 1/24 (i.e. each output time step represents a separate frame in a 24 fps sequence).

• export_for (str, optional) –

  An optional argument that will adjust the data to be more in keeping with certain software package conventions E.g. "unreal" will export the data with a Z-up coordinate system, left-hand rule, and in centimetres, whereas "opengl" will use a Y-up coordinate system, right-hand rule, and metres. Default is "opengl".

  Typically, the end software package can manipulate the data (automatically or manually by the user) to suit its own requirements, however this option is provided to make the import process easier.

  The options are:

  • "opengl"

  • "unreal"

  • "blender"

Examples

The examples below show videos of the exported Alembic files in Blender for visualisation.

Export the water level from an XMDF result with depth and vector velocity as vertex colours:

>>> from pytuflow import XMDF
>>> xmdf = XMDF('/path/to/result.xmdf')
>>> xmdf.to_alembic(
    output_path='/path/to/output/water_level.abc',
    mesh_geometry='water level',
    vertex_colour=['depth', 'vector velocity-x', 'vector velocity-y'],
    time_sampling=0.5,  # 0.5 second intervals
    export_for='blender'
)