pyvale.render.uvtools module¶

Renderer independent tools for generating and transforming nodal UVs.

Texture shapes follow NumPy convention, (height, width). Pixel coordinates refer to pixel centres, so the final pixel centres are at width - 1 and height - 1. UV arrays have shape (node_count, 2).

class EUVBounds(*values)[source]¶

Bases: Enum

Handling for physically scaled UVs outside the source texture.

SATURATE = 'saturate'¶

TILED = 'tiled'¶

class EUVFit(*values)[source]¶

Bases: Enum

Rule used to fit projected coordinates into texture bounds.

CONTAIN = 'contain'¶

FIT_U = 'fit_u'¶

FIT_V = 'fit_v'¶

STRETCH = 'stretch'¶

class EUVOrigin(*values)[source]¶

Bases: Enum

Location of the texture space V origin.

UPPER_LEFT = 'upper_left'¶

LOWER_LEFT = 'lower_left'¶

class EUVPlane(*values)[source]¶

Bases: Enum

Axis aligned plane used for planar UV projection.

XY = 'xy'¶

YZ = 'yz'¶

XZ = 'xz'¶

class UVMapping(uvs, texture, tile_counts=(1, 1))[source]¶

Bases: object

UV coordinates and the texture image they address.

TILED mappings may contain an expanded texture assembled from the supplied source image. tile_counts is in (U, V) order.

Parameters:

uvs (np.ndarray) – Nodal UV coordinate array with shape (num_nodes, 2) and dtype float64 in the normalized range [0.0, 1.0].
texture (np.ndarray) – Texture image array with shape (height, width) or (height, width, num_channels).
tile_counts (tuple[int, int], optional) – Number of tiles in U and V directions (tile_u, tile_v). Defaults to (1, 1).

uvs¶

texture¶

tile_counts¶

__init__(uvs, texture, tile_counts=(1, 1))¶

class UVPlane(normal, origin, up=None)[source]¶

Bases: object

Arbitrary projection plane.

Parameters:

normal (np.ndarray) – Nonzero plane normal vector array with shape (3,) and dtype float64 representing (nx, ny, nz).
origin (np.ndarray) – Point on the plane with shape (3,) and dtype float64 representing (x, y, z) coordinates.
up (np.ndarray or None, optional) – Preferred positive V direction array with shape (3,) and dtype float64. Its component normal to the plane is removed. When omitted, a deterministic basis is constructed.

normal¶

origin¶

up¶

__init__(normal, origin, up=None)¶

class UVTransform(translation=(0.0, 0.0), rotation_degrees=0.0, scale=(1.0, 1.0), pivot=(0.5, 0.5))[source]¶

Bases: object

Affine UV transform applied about a pivot before translation.

Parameters:

translation (tuple[float, float], optional) – Translation offset in UV space (du, dv). Defaults to (0.0, 0.0).
rotation_degrees (float, optional) – Rotation angle in degrees about the pivot. Defaults to 0.0.
scale (tuple[float, float], optional) – Scale factor in UV space (su, sv). Defaults to (1.0, 1.0).
pivot (tuple[float, float], optional) – Pivot center point in UV space (pu, pv). Defaults to (0.5, 0.5).

translation¶

rotation_degrees¶

scale¶

pivot¶

__init__(translation=(0.0, 0.0), rotation_degrees=0.0, scale=(1.0, 1.0), pivot=(0.5, 0.5))¶

uv_calc_feature_leng(image_px_per_feature, image_leng_per_px)[source]¶

Calculate physical feature size or pitch from its rendered size.

Parameters:

image_px_per_feature (float) – Target feature size in rendered pixels.
image_leng_per_px (float) – Physical length per image pixel at the specimen plane.

Returns:

float – Physical feature length in simulation length units.

Raises:

ValueError – If any input is not positive.

uv_calc_image_px_per_feature(feature_leng, image_leng_per_px)[source]¶

Calculate rendered pixels per feature size or pitch.

Parameters:

feature_leng (float) – Physical feature dimension in simulation length units.
image_leng_per_px (float) – Physical length per image pixel at the specimen plane.

Returns:

float – Rendered feature dimension in pixel units.

Raises:

ValueError – If any input is not positive.

uv_calc_texture_px_per_leng(texture_px_per_feature, feature_leng)[source]¶

Calculate texture pixels per simulation length unit.

Parameters:

texture_px_per_feature (float) – Feature dimension in texture pixels.
feature_leng (float) – Feature physical dimension in simulation length units.

Returns:

float – Texture pixels per simulation length unit.

Raises:

ValueError – If any input is not positive.

uv_calc_texture_px_per_leng_from_image(texture_px_per_feature, image_px_per_feature, image_leng_per_px)[source]¶

Calculate texture scale for a desired rendered feature size.

Parameters:

texture_px_per_feature (float) – Feature dimension in source texture pixels.
image_px_per_feature (float) – Desired feature dimension in rendered image pixels.
image_leng_per_px (float) – Physical length per image pixel at the specimen plane.

Returns:

float – Required texture pixels per simulation length unit.

uv_from_pixels(pixel_coords, texture_shape, origin=EUVOrigin.UPPER_LEFT)[source]¶

Convert pixel centre coordinates to normalized UV coordinates.

Parameters:

pixel_coords (np.ndarray) – Pixel coordinate array with shape (num_nodes, 2) and dtype float64 representing (px_x, px_y).
texture_shape (tuple[int, int]) – Texture image shape (height, width).
origin (EUVOrigin, optional) – Texture space vertical origin (EUVOrigin.UPPER_LEFT or EUVOrigin.LOWER_LEFT). Defaults to EUVOrigin.UPPER_LEFT.

Returns:

np.ndarray – Normalized UV coordinates array with shape (num_nodes, 2) and dtype float64 in the range [0.0, 1.0].

Raises:

ValueError – If origin is unsupported or input shapes are invalid.

uv_map_planar_scaled(coords, texture, texture_px_per_leng, plane=EUVPlane.XY, texture_center_px=None, origin=EUVOrigin.UPPER_LEFT, bounds=EUVBounds.SATURATE)[source]¶

Map a planar surface using a fixed physical texture scale.

The projected specimen centre is placed at texture_center_px. When no centre is supplied, the centre of the source texture is used. Texture scale may be one isotropic value or independent (U, V) values.

Parameters:

coords (np.ndarray) – Nodal coordinates array with shape (num_nodes, 3) and dtype float64.
texture (np.ndarray) – Source texture image array with shape (height, width) or (height, width, num_channels).
texture_px_per_leng (float or np.ndarray) – Physical texture resolution as a scalar or two element array with shape (2,) and dtype float64 for (scale_u, scale_v).
plane (EUVPlane or UVPlane, optional) – Projection plane. Defaults to EUVPlane.XY.
texture_center_px (np.ndarray or None, optional) – Pixel coordinate array with shape (2,) and dtype float64 denoting the texture centre.
origin (EUVOrigin, optional) – Vertical origin convention. Defaults to EUVOrigin.UPPER_LEFT.
bounds (EUVBounds, optional) – Out of bounds handling mode (EUVBounds.SATURATE or EUVBounds.TILED). Defaults to EUVBounds.SATURATE.

Returns:

UVMapping – Constructed mapping containing nodal UVs, texture image, and tile counts.

Raises:

ValueError – If inputs are invalid or out of bounds.

uv_project_planar(coords, plane=EUVPlane.XY, uv_bounds=(0.0, 0.0, 1.0, 1.0), fit=EUVFit.CONTAIN, texture_shape=None, origin=EUVOrigin.UPPER_LEFT)[source]¶

Project mesh coordinates into normalized UV bounds.

When texture_shape is omitted, a square two pixel texture is assumed for aspect fitting. Supply the actual image shape when its aspect ratio should influence CONTAIN, FIT_U, or FIT_V.

Parameters:

coords (np.ndarray) – Nodal coordinates array with shape (num_nodes, 3) and dtype float64.
plane (EUVPlane or UVPlane, optional) – Projection plane (default is EUVPlane.XY).
uv_bounds (tuple[float, float, float, float], optional) – Normalized UV bounds (min_u, min_v, max_u, max_v). Defaults to (0.0, 0.0, 1.0, 1.0).
fit (EUVFit, optional) – Fitting mode (default is EUVFit.CONTAIN).
texture_shape (tuple[int, int] or None, optional) – Image shape (height, width) for aspect preservation.
origin (EUVOrigin, optional) – Vertical origin convention. Defaults to EUVOrigin.UPPER_LEFT.

Returns:

np.ndarray – Nodal UV coordinates array with shape (num_nodes, 2) and dtype float64.

Raises:

ValueError – If UV bounds are inverted or origin is invalid.

uv_project_planar_centered(coords, texture_shape, *, span=1.0, plane=EUVPlane.XY, origin=EUVOrigin.UPPER_LEFT)[source]¶

Project coordinates into a centred aspect preserving UV region.

Parameters:

coords (np.ndarray) – Nodal coordinates array with shape (num_nodes, 3) and dtype float64.
texture_shape (tuple[int, int]) – Texture image shape (height, width).
span (float, optional) – Fraction of texture bounds to occupy (0 < span <= 1.0). Defaults to 1.0.
plane (EUVPlane or UVPlane, optional) – Projection plane. Defaults to EUVPlane.XY.
origin (EUVOrigin, optional) – Vertical origin convention. Defaults to EUVOrigin.UPPER_LEFT.

Returns:

np.ndarray – Nodal UV coordinates array with shape (num_nodes, 2) and dtype float64.

Raises:

ValueError – If span is not in the interval (0, 1].

uv_project_planar_pixels(coords, texture_shape, pixel_bounds, plane=EUVPlane.XY, fit=EUVFit.CONTAIN, origin=EUVOrigin.UPPER_LEFT)[source]¶

Project mesh coordinates into a texture space pixel rectangle.

Parameters:

coords (np.ndarray) – Nodal coordinates array with shape (num_nodes, 3) and dtype float64.
texture_shape (tuple[int, int]) – Texture image dimensions (height, width).
pixel_bounds (tuple[float, float, float, float]) – Target pixel bounds (min_x, min_y, max_x, max_y).
plane (EUVPlane or UVPlane, optional) – Projection plane (default is EUVPlane.XY).
fit (EUVFit, optional) – Fitting rule within the pixel bounds (default is EUVFit.CONTAIN).
origin (EUVOrigin, optional) – Vertical origin convention. Defaults to EUVOrigin.UPPER_LEFT.

Returns:

np.ndarray – Nodal UV coordinate array with shape (num_nodes, 2) and dtype float64.

uv_to_pixels(uvs, texture_shape, origin=EUVOrigin.UPPER_LEFT)[source]¶

Convert normalized UV coordinates to pixel centre coordinates.

Parameters:

uvs (np.ndarray) – Normalized UV coordinate array with shape (num_nodes, 2) and dtype float64.
texture_shape (tuple[int, int]) – Texture image shape (height, width).
origin (EUVOrigin, optional) – Texture space vertical origin. Defaults to EUVOrigin.UPPER_LEFT.

Returns:

np.ndarray – Pixel coordinate array with shape (num_nodes, 2) and dtype float64.

Raises:

ValueError – If origin is unsupported or input shapes are invalid.

uv_transform(uvs, transform)[source]¶

Scale and rotate UVs about a pivot, then apply translation.

Parameters:

uvs (np.ndarray) – Nodal UV coordinate array with shape (num_nodes, 2) and dtype float64.
transform (UVTransform) – Affine transform specifying scale, rotation, translation, and pivot.

Returns:

np.ndarray – Transformed UV coordinate array with shape (num_nodes, 2) and dtype float64.

Raises:

ValueError – If rotation is not finite or UV coordinates have invalid shape.