¶Neural Training

The Neural Training script is a Python script designed to run the AdonisML training process from a standalone Python entry point or from a command-line interface.

This script is DCC-independent. It can be run from a standalone environment or from a DCC Python environment, as long as the required AdonisML dependencies, license, and input data are available.

The script trains an .adnm model from the input and output .csv files generated by the data extraction workflow. It can also use neural cluster data generated by the AdnNeuralClusteringPaintTool to provide locality information during training.

The training script can be launched directly from Python using the train function in adnml.scripts.train, or through a command-line interface using the supported command-line arguments.

The AdnMLTraining TOP HDA wraps this same training process and provides a Houdini UI workflow to configure and launch training interactively.

The training script checks out an Adonis license while the training process is running. The license product depends on the execution mode. Standalone or automated training usually uses the "batch" license product, while DCC-driven interactive execution can use the "interactive" license product.

¶Requirements

To run Neural Training, the AdonisML training dependencies must be installed.

Dependency installation is handled by platform-specific scripts. For information about where to find and run these scripts, please refer to this section on the Installation page.

The training script automatically checks for GPU devices to accelerate the training process. If no compatible GPU is found, training will fall back to CPU execution and can be slower.

The following arguments are required:

• in_filepath: Input data inputs.csv file used for training.
• out_filepath: Output data outputs.csv file used for training.
• model_target_path: Output .adnm model path.

The input and output data files must be generated by the data extraction workflow.

If the output model path does not use the .adnm extension, the script appends it automatically.

When training with neural clusters, the following additional files are required:

• clusters_filepath: Neural cluster .json file generated by the AdnNeuralClusteringPaintTool.
• joint_info_filepath: Joint information .json file generated during data extraction. This file should be selected from the same dataset folder as the input and output data files generated during data extraction.

If clusters_filepath is provided, joint_info_filepath must also be provided so the training process can associate the neural clusters with the joints expected in the recorded dataset.

The neural cluster data must be defined for the same joint set used to extract the dataset.

¶Arguments

The main Python function to launch training is train, which is defined as follows:

from adnml.scripts.train import train
from adnml.utils.constants import AugmentationProtocols

def train(
    in_filepath,                              # str: filepath to the input CSV data.
    out_filepath,                             # str: filepath to the output CSV data.
    model_target_path,                        # str: path where the trained model will be saved.
    clusters_filepath="",                     # str: optional path to the neural cluster JSON file.
    joint_info_filepath="",                   # str: optional path to the recorded joint info JSON file.
    aug_protocol=AugmentationProtocols.NONE,  # AugmentationProtocols | str: data augmentation protocol.
    force_wait=True,                          # bool: whether to wait for input before closing the terminal.
    standardize_in=False,                     # bool: whether to standardize input data.
    standardize_out=False,                    # bool: whether to standardize output data.
    use_only_aug=False,                       # bool: whether to train using only augmented data.
    force_overwrite=False,                    # bool: whether to overwrite the model file if it exists.
    license_product="batch"                   # str: Adonis license product type.
)

The train function launches the training process using the provided training data, output model path, and optional training settings.

The following table lists the Python arguments and their command-line equivalents:

Standardization. The script supports standardization for both input and output data. For most training runs, output standardization is recommended because it can improve training stability and results. If the number of training poses is low, it may be better to disable output standardization to preserve the original data distribution.

Neural clusters. Neural cluster data can be provided with clusters_filepath or --clustersfilepath. When neural clusters are used, the training process also requires the joint information file through joint_info_filepath or --joint-info-filepath. The neural cluster .json file is generated by the AdnNeuralClusteringPaintTool.

Augmentation. The aug_protocol argument controls which data augmentation protocol is used. The available protocols are "none", "simple", and "random". Augmentation uses neural clusters to generate new synthetic poses from the training samples. These generated poses may contain artifacts and may be less aligned to the original simulated silhouette.

License product. Use the license product for which you have an active license. Standalone or automated training usually uses "batch", while DCC-driven interactive execution can use "interactive".

¶How To Use

¶Run from DCC Python Interpreter

Use this mode when running from a DCC instance where the Adonis plugin is loaded and adnml is available.

from adnml.scripts.train import train

train(
    in_filepath="path/to/dataset/inputs.csv",
    out_filepath="path/to/dataset/outputs.csv",
    model_target_path="path/to/output/model.adnm",
    standardize_out=True,
    license_product="interactive"
)

To train with neural clusters, provide the neural cluster .json file and the joint information .json file:

from adnml.scripts.train import train
from adnml.utils.constants import AugmentationProtocols

train(
    in_filepath="path/to/dataset/inputs.csv",
    out_filepath="path/to/dataset/outputs.csv",
    model_target_path="path/to/output/model.adnm",
    clusters_filepath="path/to/clusters/neural_clusters.json",
    joint_info_filepath="path/to/dataset/joints.json",
    aug_protocol=AugmentationProtocols.NONE,
    standardize_out=True,
    license_product="interactive"
)

To overwrite an existing model, enable force_overwrite only if the existing .adnm file can be safely replaced:

from adnml.scripts.train import train

train(
    in_filepath="path/to/dataset/inputs.csv",
    out_filepath="path/to/dataset/outputs.csv",
    model_target_path="path/to/output/model.adnm",
    standardize_out=True,
    force_overwrite=True,
    license_product="interactive"
)

For a Houdini UI workflow, use the AdnMLTraining TOP HDA.

¶Run from Standalone Python Interpreter

Use this mode when running the training script from a standalone Python interpreter.

Before launching the script, set PYTHONPATH so the interpreter can find the Adonis Python modules.

On Windows, run:

set PYTHONPATH=<path_to_adn_plugin_folder>/python

On Linux, run:

export PYTHONPATH=<path_to_adn_plugin_folder>/python

Then launch the training script with the standalone Python interpreter.

On Windows, run:

"<your_python_interpreter>/python.exe" "<path_to_adn_plugin_folder>/python/adnml/scripts/train.py" ^
  --input-data "C:/path/to/dataset/inputs.csv" ^
  --output-data "C:/path/to/dataset/outputs.csv" ^
  --modelpath "C:/path/to/output/model.adnm" ^
  --standardize-out ^
  --license-product batch ^
  --force-wait

On Linux, run:

"<your_python_interpreter>/python" "<path_to_adn_plugin_folder>/python/adnml/scripts/train.py" \
  --input-data "/path/to/dataset/inputs.csv" \
  --output-data "/path/to/dataset/outputs.csv" \
  --modelpath "/path/to/output/model.adnm" \
  --standardize-out \
  --license-product batch \
  --force-wait

To train with neural clusters from the standalone Python interpreter, provide the neural cluster .json file and the joint information .json file:

"<your_python_interpreter>/python.exe" "<path_to_adn_plugin_folder>/python/adnml/scripts/train.py" ^
  --input-data "C:/path/to/dataset/inputs.csv" ^
  --output-data "C:/path/to/dataset/outputs.csv" ^
  --modelpath "C:/path/to/output/model.adnm" ^
  --clustersfilepath "C:/path/to/clusters/neural_clusters.json" ^
  --joint-info-filepath "C:/path/to/dataset/joints.json" ^
  --aug-protocol none ^
  --standardize-out ^
  --license-product batch ^
  --force-wait

Replace <path_to_adn_plugin_folder> with the folder that contains the Adonis Python package, and replace <your_python_interpreter> with the Python interpreter used to run training.

¶Result

As a result of executing the script, the output folder will contain the trained model and the training support files:

• <model_name>.adnm
• <model_name>_log.txt
• <model_name>_config.json

The resulting .adnm file can then be used as part of the Adonis neural workflow.

The <model_name>_log.txt file can be used to inspect the training process. It contains epoch information, average loss, best loss, warnings, errors, and other training messages.

The <model_name>_config.json file can be used to review the training configuration used to produce the model.

¶Recommendations

• Keep the input data, output data, and joint info files together in the same dataset folder.
• Use standardize_out or --standardize-out for most training runs.
• Consider disabling output standardization only when the number of training poses is low and preserving the original output distribution gives better results.
• Use neural clusters when local deformation regions should be enforced in the trained model predictions.
• Use augmentation only when the dataset is small and training without augmentation is not producing good results. If possible, recording new data should be considered first. Augmented poses may contain artifacts and may be less aligned to the original simulated silhouette.
• Prefer GPU training when compatible hardware and dependencies are available, because it is usually faster than CPU training.
• Use the license product for which you have an active license.
• Review the generated <model_name>_log.txt file after training to inspect epoch progress and loss values.
• Review the generated <model_name>_config.json file to confirm the training configuration used for the model.
• Use force_overwrite or --force-overwrite carefully, because it deletes any existing model file at the target path.

¶Troubleshooting

If the training process fails or does not produce the expected result, check the following:

1. Confirm that the training dependencies are installed.

   Make sure to install the training dependencies before launching the training process. For more information, refer to the installation documentation.

2. Confirm that the correct license product is being used.

   Make sure to use a license product for which you have an active license.

3. Check the generated <model_name>_log.txt file.

   The log file is generated next to the .adnm model and contains detailed training information, including epochs, losses, warnings, and errors.

4. Check the generated <model_name>_config.json file.

   The config file records the training parameters used for the run. This can help confirm that the correct input data, output data, neural cluster settings, augmentation settings, license product, and output options were used.

5. Confirm that the model path is valid.

   The output model path should point to the desired output model location. If the .adnm extension is missing, the script appends it automatically.

6. Confirm that the input and output data paths are valid.

   The in_filepath and out_filepath arguments must point to valid inputs.csv and outputs.csv files.

7. Confirm that neural cluster paths are valid when using neural clusters.

   If clusters_filepath is provided, make sure joint_info_filepath is also provided and points to the joint information .json file from the extracted dataset.

8. Confirm that the cluster information is defined for the same joints as the dataset.

   The neural cluster data should be associated with the same joint set used when extracting the dataset.

9. Confirm that the model converged during training.

   The training process stops automatically when the predicted outputs stop improving. If the log shows training stopped after a small number of epochs, for example fewer than 100, try recording new data or adjusting the cluster definitions. Datasets that are too small or clusters with too many overlapping regions can be detrimental for learning.

¶Limitations

• Multi-GPU setups are currently not supported and the training will use the first available device.