unreal.NearestNeighborModel

class unreal.NearestNeighborModel(outer: Object | None = None, name: Name | str = 'None')

Bases: MLDeformerMorphModel

The nearest neighbor model. This model contains the PCA basis of the cloth vertex deltas and a small set of cloth for nearest neighbor search. Given a new pose, the pre-trained neural network first predicts the PCA coefficients of the vertex deltas. Then this model uses the predicted PCA coeffcients to find a nearest neighbor in the small cloth set. The total vertex delta is computed by

vertex_delta = mean_delta + pca_basis * pca_coeff + nearest_neighbor_delta

To prevent popping, a time filtering is applied on predicted vertex deltas. The vertex delta at time t is computed by

vertex_delta(t) = decay_factor * vertex_delta(t-1) + (1 - decay_factor) * vertex_delta

The cloth can be separated into several parts (e.g. shirt, pants…). The nearest neighbor search is carried out separately for each part. The pca basis and the nearest neighbor data are compressed into morph targets.

C++ Source:

• Plugin: NearestNeighborModel

• Module: NearestNeighborModel

• File: NearestNeighborModel.h

Editor Properties: (see get_editor_property/set_editor_property)

• alignment_transform (Transform): [Read-Write] The transform that aligns the Geometry Cache to the SkeletalMesh. This will mostly apply some scale and a rotation, but no translation.

• anim_sequence (AnimSequence): [Read-Write] The animation sequence to apply to the base mesh. This has to match the animation of the target mesh’s geometry cache. Internally we force the Interpolation property for this motion to be “Step”.

• basis_smooth_iter (int32): [Read-Write]

• batch_size (int32): [Read-Write]

• bone_include_list (Array[BoneReference]): [Read-Write] The bones to include during training. When none are provided, all bones of the Skeleton will be included.

• cloth_part_editor_data (Array[ClothPartEditorData]): [Read-Write]

• curve_include_list (Array[MLDeformerCurveReference]): [Read-Write] The curves to include during training. When none are provided, all curves of the Skeleton will be included.

• decay_factor (float): [Read-Write]

• delta_cutoff_length (float): [Read-Write] Sometimes there can be some vertices that cause some issues that cause deltas to be very long. We can ignore these deltas by setting a cutoff value. Deltas that are longer than the cutoff value (in units), will be ignored and set to zero length.

• file_cache_directory (str): [Read-Write]

• geometry_cache (GeometryCache): [Read-Write] The geometry cache that represents the target deformations.

• hidden_layer_dims (Array[int32]): [Read-Write]

• include_bones (bool): [Read-Write] Specifies whether bone transformations should be included as inputs during the training process.

• include_curves (bool): [Read-Write] Specifies whether curve values (a float per curve) should be included as inputs during the training process.

• include_normals (bool): [Read-Write] Include vertex normals in the morph targets? The advantage of this can be that it is higher performance than recomputing the normals. The disadvantage is it can result in lower quality and uses more memory for the stored morph targets.

• input_dim (int32): [Read-Only]

• input_multipliers (Array[Vector3f]): [Read-Write]

• inputs_max (Array[float]): [Read-Write]

• inputs_min (Array[float]): [Read-Write]

• invert_mask_channel (bool): [Read-Write] Enable this if you want to invert the mask channel values. For example if you painted the neck seam vertices in red, and you wish the vertices that got painted to NOT move, you have to invert the mask. On default you paint areas where the deformer should be active. If you enable the invert option, you paint areas where the deformer will not be active.

• k_means_part_id (int32): [Read-Write]

• learning_rate (float): [Read-Write]

• mask_channel (MLDeformerMaskChannel): [Read-Write] The channel data that represents the delta mask multipliers. You can use this feather out influence of the ML Deformer in specific areas, such as neck line seams, where the head mesh connects with the body. The painted vertex color values will be like a weight multiplier on the ML deformer deltas applied to that vertex. You can invert the mask as well.

• max_training_frames (int32): [Read-Write] The maximum numer of training frames (samples) to train on. Use this to train on a sub-section of your full training data.

• morph_compression_level (float): [Read-Write] The morph target compression level. Higher values result in larger compression, but could result in visual artifacts. Most of the times this is a value between 20 and 200.

• morph_data_size (float): [Read-Only]

• morph_delta_zero_threshold (float): [Read-Write] Morph target delta values that are smaller than or equal to this threshold will be zeroed out. This essentially removes small deltas from morph targets, which will lower the memory usage at runtime, however when set too high it can also introduce visual artifacts. A value of 0 will result in the highest quality morph targets, at the cost of higher runtime memory usage.

• nearest_neighbor_data (Array[SkeletonCachePair]): [Read-Write]

• nearest_neighbor_offset_weight (float): [Read-Write]

• num_clusters (int32): [Read-Write]

• num_epochs (int32): [Read-Write]

• output_dim (int32): [Read-Only]

• quality_levels (Array[MLDeformerMorphModelQualityLevel]): [Read-Write] The list of quality levels, where the first item represents the highest quality and the last element the lowest quality level. The number in each quality level represents the number of active morph targets for that quality level. These numbers will be clamped internally to be within valid ranges in case they go beyond the amount of morphs that exist.

• recompute_deltas (bool): [Read-Write]

• recompute_pca (bool): [Read-Write]

• saved_network_size (float): [Read-Only]

• skeletal_mesh (SkeletalMesh): [Read-Write] The skeletal mesh that represents the linear skinned mesh.

• source_anims (Array[AnimSequence]): [Read-Write]

• use_dual_quaternion_deltas (bool): [Read-Write]

• use_file_cache (bool): [Read-Write]

• use_input_multipliers (bool): [Read-Write]

• use_part_only_mesh (bool): [Read-Write]

property basis_smooth_iter: int

[Read-Write]

Type:

(int32)

property batch_size: int

[Read-Write]

Type:

(int32)

clip_inputs(input) → Array[float]

Clip Inputs

Parameters:

input (Array[float]) –

Return type:

Array[float]

property cloth_part_editor_data: None

[Read-Write]

Type:

(Array[ClothPartEditorData])

property decay_factor: float

[Read-Write]

Type:

(float)

property file_cache_directory: str

[Read-Write]

Type:

(str)

get_batch_size() → int32

Get Batch Size

Return type:

int32

get_cloth_part_editor_data() → Array[ClothPartEditorData]

Get Cloth Part Editor Data

Return type:

Array[ClothPartEditorData]

get_hidden_layer_dims() → Array[int32]

Get Hidden Layer Dims

Return type:

Array[int32]

get_input_dim() → int32

Get Input Dim

Return type:

int32

get_learning_rate() → float

Get Learning Rate

Return type:

float

get_model_dir() → str

Get Model Dir

Return type:

str

get_nearest_neighbor_data() → Array[SkeletonCachePair]

Get Nearest Neighbor Data

Return type:

Array[SkeletonCachePair]

get_num_epochs() → int32

Get Num Epochs

Return type:

int32

get_num_neighbors(part_id) → int32

Get Num Neighbors

Parameters:

part_id (int32) –

Return type:

int32

get_num_parts() → int32

Get Num Parts

Return type:

int32

get_output_dim() → int32

Get Output Dim

Return type:

int32

get_part_num_verts(part_id) → int32

Get Part Num Verts

Parameters:

part_id (int32) –

Return type:

int32

get_pca_coeff_num(part_id) → int32

Get PCACoeff Num

Parameters:

part_id (int32) –

Return type:

int32

get_pca_coeff_start(part_id) → int32

Get PCACoeff Start

Parameters:

part_id (int32) –

Return type:

int32

property hidden_layer_dims: None

[Read-Write]

Type:

(Array[int32])

property input_dim: int

[Read-Only]

Type:

(int32)

property input_multipliers: None

[Read-Write]

Type:

(Array[Vector3f])

property inputs_max: None

[Read-Write]

Type:

(Array[float])

property inputs_min: None

[Read-Write]

Type:

(Array[float])

property k_means_part_id: int

[Read-Write]

Type:

(int32)

property learning_rate: float

[Read-Write]

Type:

(float)

property morph_data_size: float

[Read-Only]

Type:

(float)

property nearest_neighbor_data: None

[Read-Write]

Type:

(Array[SkeletonCachePair])

property nearest_neighbor_offset_weight: float

[Read-Write]

Type:

(float)

neighbor_coeffs(part_id) → Array[float]

Neighbor Coeffs

Parameters:

part_id (int32) –

Return type:

Array[float]

neighbor_offsets(part_id) → Array[float]

Neighbor Offsets

Parameters:

part_id (int32) –

Return type:

Array[float]

property num_clusters: int

[Read-Write]

Type:

(int32)

property num_epochs: int

[Read-Write]

Type:

(int32)

property output_dim: int

[Read-Only]

Type:

(int32)

pca_basis(part_id) → Array[float]

PCABasis

Parameters:

part_id (int32) –

Return type:

Array[float]

property recompute_deltas: bool

[Read-Write]

Type:

(bool)

property recompute_pca: bool

[Read-Write]

Type:

(bool)

property saved_network_size: float

[Read-Only]

Type:

(float)

set_neighbor_coeffs(part_id, neighbor_coeffs) → None

Set Neighbor Coeffs

Parameters:

• part_id (int32) –

• neighbor_coeffs (Array[float]) –

set_neighbor_offsets(part_id, neighbor_offsets) → None

Set Neighbor Offsets

Parameters:

• part_id (int32) –

• neighbor_offsets (Array[float]) –

set_num_neighbors(part_id, num_neighbors) → None

Set Num Neighbors

Parameters:

• part_id (int32) –

• num_neighbors (int32) –

set_pca_basis(part_id, pca_basis) → None

Set PCABasis

Parameters:

• part_id (int32) –

• pca_basis (Array[float]) –

set_vertex_mean(part_id, vertex_mean) → None

Set Vertex Mean

Parameters:

• part_id (int32) –

• vertex_mean (Array[float]) –

property source_anims: None

[Read-Write]

Type:

(Array[AnimSequence])

property use_dual_quaternion_deltas: bool

[Read-Write]

Type:

(bool)

property use_file_cache: bool

[Read-Write]

Type:

(bool)

property use_input_multipliers: bool

[Read-Write]

Type:

(bool)

property use_part_only_mesh: bool

[Read-Write]

Type:

(bool)

vertex_mean(part_id) → Array[float]

Vertex Mean

Parameters:

part_id (int32) –

Return type:

Array[float]