HVE Toolkit — User Guide

A hands-on guide to using the HVE Toolkit add-on for Blender: HVE simulation setup, H3D export, and result import.

This guide walks you through installing the add-on, finding its panels, and completing the most common tasks step by step. For a terse feature-by-feature reference, see README.md.

Contents

1. What this add-on does
2. Install and find the panels
3. How the sidebar is organized
4. Task guides
   • Pre-Simulation Setup
     • 4.1 Prepare objects for HVE export
     • 4.2 Export H3D files
   • Post-Simulation Processing
     • 4.3 Import post-simulation results
5. Units and scale
6. Troubleshooting

1. What this add-on does

HVE Toolkit bridges Blender and HVE (Human Vehicle Environment) simulation workflows: set up and export scene objects (vehicles, environments, GATB surfaces) as HVE .h3d files, and import simulation results back into Blender (variable-output CSV/HVO, HVE FBX, RaceRender conversion).

The add-on gets its own sidebar tab in the 3D View (EDC Toolkits by default).

2. Install and find the panels

1. Install Blender 4.x or later.
2. Download HVEToolkit-<version>.zip from the latest release (or clone this repository and run python tools/build_release.py to build dist/HVEToolkit-<version>.zip).
3. In Blender: Edit → Preferences → Add-ons → Install…, then select the add-on .zip.
4. Tick HVE Toolkit in the add-ons list to enable it.
5. In the 3D View, press N to open the sidebar, then click the EDC Toolkits tab.

Tip — rename the tab. The add-on's preferences (Edit → Preferences → Add-ons, expand the add-on) let you choose the sidebar tab name: the default EDC Toolkits, HVE, Human Vehicle Environment, or a custom name.

If you don't see the tab, confirm the add-on is enabled and that you are in the 3D View (not, say, the Shader Editor).

3. How the sidebar is organized

Everything sits inside one HVE Toolkit dropdown in the tab (so other EDC add-ons can share the tab, each under its own heading), with these panels:

Most panels are collapsed by default — click a panel header to expand it. The task guides below follow this same order: Pre-Simulation Setup, then Post-Simulation Processing.

4. Task guides

Each subsection below is a self-contained task, ordered to match the panels in the sidebar.

Pre-Simulation Setup

4.1 Prepare objects for HVE export

Open Pre-Simulation Setup → H3D Setup, then:

1. Add Materials — expand and click Add Materials to create the generic, standard, and HVE light material sets.
2. Object Type — expand and classify the selected object as Environment, Vehicle, or GATB Surface. If you selected several objects of mixed types, use the one-click reclassify buttons shown in the warning.
3. Vehicle Lighting (vehicles only) — tag light objects (headlights, brake, turn, fog, reverse, tail, etc.) so HVE knows their function.
4. Terrain Properties (environments only) — set:
   • Surface: type (Road / Friction Zone / Curb / Water / Other), overlay label, material name, friction multiplier. The Copy Type + Overlay to Selected button pushes surface type and overlay from the active object to the rest of the selection.
   • Water: depth and static-water flag.
   • Soil: Bekker exponent, frictional/cohesive modifiers, moisture, macrotexture.
   • Forces: constant, linear, quadratic, cubic, unloading, damping.
5. Optionally Save Preset / Load Preset, or pick one from Apply Preset, to reuse terrain settings (presets live in hve_presets/).

4.2 Export H3D files

1. Select the object(s) to export and confirm their HVE type in H3D Setup.
2. Open Pre-Simulation Setup → Export to HVE. The button adapts to the selected type:
   • Export Vehicle → .h3d
   • Export Environment → .h3d
   • Export GATB Surfaces → .csv
3. If a mixed selection is detected, classify everything as one type first (the panel offers buttons to do this).
4. In the file browser, set options (selection-only, hierarchy, normals, compression, axis conversion, global scale) and save.

Post-Simulation Processing

4.3 Import post-simulation results

Open Post-Simulation Processing and pick the matching importer:

• HVE FBX Importer — click Import FBX and choose the .fbx. On import, the HVE hierarchy is renamed into cleaner labels, the scene timeline is extended to cover the animation, and objects are organized into HVE collections by event, vehicle, wheels, and body. Then set Max Shape Key Samples (the cap on shape keys kept per mesh; 0 = no cap) and click Process Imported FBX to run the Reduce Keys → Merge Meshes → Smooth cleanup pipeline. Use the Process Collection selector below the button to limit processing to the body meshes nested under one collection (leave empty to process every imported vehicle).
• Variable Output Importer — import an HVE .hvo/.csv of time plus variable-output columns. Choose feet or meters, optionally override the scale factor, and optionally save separate vehicle CSV files.
• RaceRender Converter — convert HVE variable output into RaceRender-ready .csv files.

5. Units and scale

• Variable Output Importer: choose feet or meters to match the HVE output; the optional scale factor override gives finer control.
• H3D export: the file browser exposes a global scale option, and the GATB surface export has its own global scale setting.
• Set the scene unit system in Blender's Scene Properties → Units before importing so conversions match your data.

6. Troubleshooting

The EDC Toolkits tab is missing. Make sure the HVE Toolkit add-on is enabled in Preferences, you're in the 3D View, and the sidebar is open (N). Check the tab name in the add-on's preferences.

The export button warns about mixed HVE object types. The selection contains objects classified as different types — use the one-click reclassify buttons in the warning (or H3D Setup → Object Type) to make the selection one type, then export.

For a compact feature list and developer notes, see README.md.