lagrange.xatlas

Attributes

ErrorIfMultiple

NormalizePerTile

Udim

Classes

MultiAtlasPolicy

How to encode multi-atlas output.

Functions

repack_mesh(mesh, *[, max_chart_size, padding, ...])

Repack the existing UV islands of a mesh using xatlas.

repack_scene(scene, *[, max_chart_size, padding, ...])

Repack all UV islands in a scene using xatlas. See repack_mesh() for parameter docs.

unwrap_mesh(mesh, *[, max_chart_area, ...])

Unwrap a single mesh using xatlas (segmentation + parameterization + packing).

unwrap_scene(scene, *[, max_chart_area, ...])

Unwrap all meshes in a scene using xatlas. See unwrap_mesh() for parameter docs.

Module Contents

class lagrange.xatlas.MultiAtlasPolicy

Bases: enum.Enum

How to encode multi-atlas output.

ErrorIfMultiple = 2

Throw if xatlas produces more than one atlas tile.

NormalizePerTile = 0

UVs are normalized inside each atlas tile; tile id is stored separately.

Udim = 1

UVs include integer U offset = atlasIndex; V stays normalized in [0, 1].

lagrange.xatlas.repack_mesh(mesh, *, max_chart_size=0, padding=0, texels_per_unit=0.0, resolution=0, bilinear=True, block_align=False, brute_force=False, rotate_charts_to_axis=True, rotate_charts=True, input_uv_attribute_name='', input_chart_attribute_name='', output_uv_attribute_name='@uv', output_atlas_attribute_name='', output_chart_attribute_name='', multi_atlas_policy=MultiAtlasPolicy.NormalizePerTile, enable_sharing_uvs_between_instances=False)

Repack the existing UV islands of a mesh using xatlas.

The mesh must be triangle-only and have an existing indexed UV attribute. All option fields are passed as keyword arguments.

Parameters:

  • mesh (lagrange.core.SurfaceMesh) – Triangle mesh with an existing indexed UV attribute.

  • max_chart_size (int) – See PackOptions.max_chart_size.

  • padding (int) – See PackOptions.padding.

  • texels_per_unit (float) – See PackOptions.texels_per_unit.

  • resolution (int) – See PackOptions.resolution.

  • bilinear (bool) – See PackOptions.bilinear.

  • block_align (bool) – See PackOptions.block_align.

  • brute_force (bool) – See PackOptions.brute_force.

  • rotate_charts_to_axis (bool) – See PackOptions.rotate_charts_to_axis.

  • rotate_charts (bool) – See PackOptions.rotate_charts.

  • input_uv_attribute_name (str) – Input indexed UV attribute name.

  • input_chart_attribute_name (str) – Optional per-facet chart id attribute. When set, each input UV island is pinned to its own chart (forwarded to xatlas as faceMaterialData). If empty (default), xatlas re-derives charts by flood-filling faces across shared UV edges, which can merge logically-distinct islands that touch/overlap in UV space and cause the packer to overlap or flip them. Set this to make repack preserve the existing island decomposition.

  • output_uv_attribute_name (str) – Output indexed UV attribute name. If the attribute already exists, its value type is preserved; otherwise, a new attribute is created using the mesh Scalar type.

  • output_atlas_attribute_name (str) – Corner-attribute name for the per-corner atlas tile id.

  • output_chart_attribute_name (str) – Corner-attribute name for the per-corner chart id.

  • multi_atlas_policy (MultiAtlasPolicy) – How to encode multi-atlas output.

  • enable_sharing_uvs_between_instances (bool) – Scene-only; ignored for single-mesh repack.

Returns:

A new mesh with the repacked UV attribute.

Return type:

core.SurfaceMesh

lagrange.xatlas.repack_scene(scene, *, max_chart_size=0, padding=0, texels_per_unit=0.0, resolution=0, bilinear=True, block_align=False, brute_force=False, rotate_charts_to_axis=True, rotate_charts=True, input_uv_attribute_name='', input_chart_attribute_name='', output_uv_attribute_name='@uv', output_atlas_attribute_name='', output_chart_attribute_name='', multi_atlas_policy=MultiAtlasPolicy.NormalizePerTile, enable_sharing_uvs_between_instances=False, per_instance_importance=[])

Repack all UV islands in a scene using xatlas. See repack_mesh() for parameter docs.

Scene-specific kwargs:

Parameters:

  • per_instance_importance (collections.abc.Sequence[float]) – Optional list of per-instance importance weights (>0, finite).

  • scene (lagrange.scene.SimpleScene3D)

  • max_chart_size (int)

  • padding (int)

  • texels_per_unit (float)

  • resolution (int)

  • bilinear (bool)

  • block_align (bool)

  • brute_force (bool)

  • rotate_charts_to_axis (bool)

  • rotate_charts (bool)

  • input_uv_attribute_name (str)

  • input_chart_attribute_name (str)

  • output_uv_attribute_name (str)

  • output_atlas_attribute_name (str)

  • output_chart_attribute_name (str)

  • multi_atlas_policy (MultiAtlasPolicy)

  • enable_sharing_uvs_between_instances (bool)

Return type:

scene.SimpleScene3D

lagrange.xatlas.unwrap_mesh(mesh, *, max_chart_area=0.0, max_boundary_length=0.0, normal_deviation_weight=2.0, roundness_weight=0.009999999776482582, straightness_weight=6.0, normal_seam_weight=4.0, texture_seam_weight=0.5, max_cost=2.0, max_iterations=1, use_input_mesh_uvs=False, fix_winding=True, max_chart_size=0, padding=0, texels_per_unit=0.0, resolution=0, bilinear=True, block_align=False, brute_force=False, rotate_charts_to_axis=True, rotate_charts=True, input_normal_attribute_name='', input_uv_attribute_name='', output_uv_attribute_name='@uv', output_atlas_attribute_name='', output_chart_attribute_name='', multi_atlas_policy=MultiAtlasPolicy.NormalizePerTile, enable_sharing_uvs_between_instances=False)

Unwrap a single mesh using xatlas (segmentation + parameterization + packing).

The mesh must be triangle-only. All option fields are passed as keyword arguments; defaults match those of the underlying xatlas C library.

Parameters:

  • mesh (lagrange.core.SurfaceMesh) – Mesh to unwrap.

  • max_chart_area (float)

  • max_boundary_length (float)

  • normal_deviation_weight (float)

  • roundness_weight (float)

  • straightness_weight (float)

  • normal_seam_weight (float)

  • texture_seam_weight (float)

  • max_cost (float)

  • max_iterations (int)

  • use_input_mesh_uvs (bool)

  • fix_winding (bool)

  • max_chart_size (int)

  • padding (int)

  • texels_per_unit (float)

  • resolution (int)

  • bilinear (bool)

  • block_align (bool)

  • brute_force (bool)

  • rotate_charts_to_axis (bool)

  • rotate_charts (bool)

  • input_normal_attribute_name (str)

  • input_uv_attribute_name (str)

  • output_uv_attribute_name (str)

  • output_atlas_attribute_name (str)

  • output_chart_attribute_name (str)

  • multi_atlas_policy (MultiAtlasPolicy)

  • enable_sharing_uvs_between_instances (bool)

Return type:

core.SurfaceMesh

Chart options (segmentation):

Parameters:

  • max_chart_area (float) – Maximum chart area in input units squared. 0 = no limit.

  • max_boundary_length (float) – Maximum chart boundary length. 0 = no limit.

  • normal_deviation_weight (float) – Cost weight on normal deviation; higher = flatter charts.

  • roundness_weight (float) – Cost weight on roundness; higher = more disk-like charts.

  • straightness_weight (float) – Cost weight on boundary straightness.

  • normal_seam_weight (float) – Cost weight on crossing normal seams. >1000 forbids crossing.

  • texture_seam_weight (float) – Cost weight on crossing input UV seams.

  • max_cost (float) – Maximum cost; faces beyond this are not merged.

  • max_iterations (int) – Number of segmentation iterations.

  • use_input_mesh_uvs (bool) – If True, treat the input UV attribute as the chart layout.

  • fix_winding (bool) – If True, ensure consistent triangle winding within charts.

  • mesh (lagrange.core.SurfaceMesh)

  • max_chart_size (int)

  • padding (int)

  • texels_per_unit (float)

  • resolution (int)

  • bilinear (bool)

  • block_align (bool)

  • brute_force (bool)

  • rotate_charts_to_axis (bool)

  • rotate_charts (bool)

  • input_normal_attribute_name (str)

  • input_uv_attribute_name (str)

  • output_uv_attribute_name (str)

  • output_atlas_attribute_name (str)

  • output_chart_attribute_name (str)

  • multi_atlas_policy (MultiAtlasPolicy)

  • enable_sharing_uvs_between_instances (bool)

Return type:

core.SurfaceMesh

Pack options:

Parameters:

  • max_chart_size (int) – Maximum chart size in pixels. 0 = no limit.

  • padding (int) – Empty pixels of padding around each chart.

  • texels_per_unit (float) – Texel-to-world ratio. 0 = auto-estimate.

  • resolution (int) – Atlas tile resolution in pixels. 0 = single tile sized by texels_per_unit.

  • bilinear (bool) – If True, leave a 1-pixel margin for safe bilinear filtering.

  • block_align (bool) – If True, align charts to 4-pixel blocks (BCn-friendly).

  • brute_force (bool) – If True, brute-force optimal placement (slow).

  • rotate_charts_to_axis (bool) – Rotate charts so longest axis aligns with U or V.

  • rotate_charts (bool) – Allow xatlas to rotate charts during packing.

  • mesh (lagrange.core.SurfaceMesh)

  • max_chart_area (float)

  • max_boundary_length (float)

  • normal_deviation_weight (float)

  • roundness_weight (float)

  • straightness_weight (float)

  • normal_seam_weight (float)

  • texture_seam_weight (float)

  • max_cost (float)

  • max_iterations (int)

  • use_input_mesh_uvs (bool)

  • fix_winding (bool)

  • input_normal_attribute_name (str)

  • input_uv_attribute_name (str)

  • output_uv_attribute_name (str)

  • output_atlas_attribute_name (str)

  • output_chart_attribute_name (str)

  • multi_atlas_policy (MultiAtlasPolicy)

  • enable_sharing_uvs_between_instances (bool)

Return type:

core.SurfaceMesh

Output options:

Parameters:

  • input_normal_attribute_name (str) – Optional vertex normal attribute used as a chart hint.

  • input_uv_attribute_name (str) – Optional UV attribute (vertex or indexed) used as a chart hint.

  • output_uv_attribute_name (str) – Output indexed UV attribute name.

  • output_atlas_attribute_name (str) – Corner-attribute name for the per-corner atlas tile id.

  • output_chart_attribute_name (str) – Corner-attribute name for the per-corner chart id.

  • multi_atlas_policy (MultiAtlasPolicy) – How to encode multi-atlas output (see MultiAtlasPolicy).

  • enable_sharing_uvs_between_instances (bool) – Scene-only; ignored for single-mesh unwrap.

  • mesh (lagrange.core.SurfaceMesh)

  • max_chart_area (float)

  • max_boundary_length (float)

  • normal_deviation_weight (float)

  • roundness_weight (float)

  • straightness_weight (float)

  • normal_seam_weight (float)

  • texture_seam_weight (float)

  • max_cost (float)

  • max_iterations (int)

  • use_input_mesh_uvs (bool)

  • fix_winding (bool)

  • max_chart_size (int)

  • padding (int)

  • texels_per_unit (float)

  • resolution (int)

  • bilinear (bool)

  • block_align (bool)

  • brute_force (bool)

  • rotate_charts_to_axis (bool)

  • rotate_charts (bool)

Returns:

A new mesh with the indexed UV attribute (and optional atlas/chart attributes).

Return type:

core.SurfaceMesh

lagrange.xatlas.unwrap_scene(scene, *, max_chart_area=0.0, max_boundary_length=0.0, normal_deviation_weight=2.0, roundness_weight=0.009999999776482582, straightness_weight=6.0, normal_seam_weight=4.0, texture_seam_weight=0.5, max_cost=2.0, max_iterations=1, use_input_mesh_uvs=False, fix_winding=True, max_chart_size=0, padding=0, texels_per_unit=0.0, resolution=0, bilinear=True, block_align=False, brute_force=False, rotate_charts_to_axis=True, rotate_charts=True, input_normal_attribute_name='', input_uv_attribute_name='', output_uv_attribute_name='@uv', output_atlas_attribute_name='', output_chart_attribute_name='', multi_atlas_policy=MultiAtlasPolicy.NormalizePerTile, enable_sharing_uvs_between_instances=False, per_instance_importance=[])

Unwrap all meshes in a scene using xatlas. See unwrap_mesh() for parameter docs.

Scene-specific kwargs:

Parameters:

  • per_instance_importance (collections.abc.Sequence[float]) – Optional list of per-instance importance weights (>0, finite).

  • scene (lagrange.scene.SimpleScene3D)

  • max_chart_area (float)

  • max_boundary_length (float)

  • normal_deviation_weight (float)

  • roundness_weight (float)

  • straightness_weight (float)

  • normal_seam_weight (float)

  • texture_seam_weight (float)

  • max_cost (float)

  • max_iterations (int)

  • use_input_mesh_uvs (bool)

  • fix_winding (bool)

  • max_chart_size (int)

  • padding (int)

  • texels_per_unit (float)

  • resolution (int)

  • bilinear (bool)

  • block_align (bool)

  • brute_force (bool)

  • rotate_charts_to_axis (bool)

  • rotate_charts (bool)

  • input_normal_attribute_name (str)

  • input_uv_attribute_name (str)

  • output_uv_attribute_name (str)

  • output_atlas_attribute_name (str)

  • output_chart_attribute_name (str)

  • multi_atlas_policy (MultiAtlasPolicy)

  • enable_sharing_uvs_between_instances (bool)

Return type:

scene.SimpleScene3D

lagrange.xatlas.ErrorIfMultiple: MultiAtlasPolicy
lagrange.xatlas.NormalizePerTile: MultiAtlasPolicy
lagrange.xatlas.Udim: MultiAtlasPolicy