Mesh importer 1100

From PopcornFX
Jump to navigation Jump to search
! IMPORTANT ! This is a PopcornFX v1 page. PopcornFX v2 documentation can be found here

See also : Editor interface overview.

This page is for version v1.10.0 and above
For the latest version of PopcornFX, see: Mesh importer


The mesh importer is what's used to import FBX meshes and animations into PopcornFX

Mesh importer

It is split in 4 sections:

1. Viewport
The viewport displays the mesh, and its animations, if it was imported with animations. It has a toolbar containing items in common with the particle editor, like render modes and the simulation-speed slider, that allows you to slow down the animations played-back in the viewport. It also contains a bunch of specific tools/buttons:
5. Grid toggle
6. Show skeleton bones
7. Show skeleton bone names
8. Show skeleton bone local basis
9. Show mesh normals
10. Show mesh tangents
11. Show mesh bitangents/binormals
12. Enable directional light
13. Enable directional light shadows
14. Auto-play animation, if any
2. Settings & treeview

This panel allows you to configure import settings.

3. Node properties

When a settings node is selected in the treeview, its properties will be displayed here.

4. Build buttom
Click this button to re-import the FBX and rebuild all internal cache files (meshes + animations).

Here are a few debug visualizations you can get with the above buttons:

Debug MeshImporter Skeleton.png Debug MeshImporter Normals.png Debug MeshImporter Tangents.png Debug MeshImporter Bitangents.png
Skeleton (#6,7,8) Normals (#9) Tangents (#10) Bitangents/Binormals (#11)

Build process

When you want to use a mesh inside PopcornFX, it first needs to be built in a format the PopcornFX understands. The editor or AssetBaker can build FBX files into those special formats.

The mesh vertices, skinning information, and skeleton, is stored inside a binary .pkmm file (standing for Popkorn multi-mesh)
The skeletal animation clips are stored inside .pksa files (standing for Popkorn skeletal animation)
The regular object animations and paths are stored inside a .pkan file, containings multiple animation tracks (standing for Popkorn animation)

Building an existing FBX

To build a new mesh that's already inside your PopcornFX project, just find the FBX in the Content browser (make sure the "Mesh" content filter is active), double-click on it to open the mesh importer, and if no built cache files are found, the viewport will be blank and the importer will automatically ask you if you want to import the mesh:

Auto-importing FBX meshes

Click yes and a progression window will be displayed until the build is complete:

FBX import progression

NOTE: The PopcornFX editor doesn't auto-rebuild FBX meshes. This means that if you already built your mesh, but modify the source FBX in max or maya or elsewhere, you will have to manually re-import it. Likewise, when upgrading to a new version of PopcornFX, sometimes the mesh formats change and are not require rebuilding cached files. This will require you rebuild all your meshes (see Batch-building multiple meshes)

Importing an external FBX

To import an external FBX, drag/drop it inside the content-browser (or copy/paste it inside your PopcornFX project directly), then build it as usual.

Batch-building multiple meshes

You can build a selection of multiple meshes, or even an entire folder, by right-clicking on the items you want to build in the Content browser, and select the "Build Assets" (Ctrl+I) menu item. A batch build will then launch, and a progression window will be displayed until the build is complete:

Batch building FBX meshes

To author and import animations paths, you can follow this short tutorial

Build settings

Build settings are saved in a .pkcf file (standing for Popkorn config) next to the source .fbx, with the same name. For example, if you have the following FBX in your project:
on first import, the PopcornFX editor will create this pkcf file:

And store all build settings inside.
pkcf files are used by the baking process, see the AssetBaker page for more details.


The Root node contains the global properties:

Field name Default value Description
Scale 1.0 Global scale

For example, if your mesh has been exported in centimeters, but your project is in meters, set this to 0.01

Endianness <empty> Internal, reserved for future use.
Mesh importer: 'General' settings


The Geometry node contains the geometry-related properties

Field name Default value Description
ImportGeometry true If disabled, will not build any geometry (usually disabled for FBX that only contain an animation path and no geom)
GeometryCompression <None> Determines if geometry should be compressed.
Positions <F32> Vertex-format in which vertex positions should be stored
  • F32 : 32-bit floating point XYZ components
  • U16 : 16-bit integer XYZ components, quantized on the mesh bounding box
Normals <F32> Vertex-format in which vertex normals should be stored
  • None : Do not import normals
  • F16 : 16-bit floating point XYZ components
  • F32 : 32-bit floating point XYZ components
Tangents <None> Vertex-format in which vertex tangents should be stored
  • None : Do not import tangents, runtime will auto-regenerate them if necessary
  • F16 : 16-bit floating point XYZ components
  • F32 : 32-bit floating point XYZ components
Texcoords <F32> Vertex-format in which vertex UV coordinates should be stored
  • None : Do not import UVs
  • F32 : 32-bit floating point UV components
  • U16 : 16-bit integer point UV components, quantized in the [0,1] range
UseTriangleStrips false If disabled, will import triangle indices as regular 3-indices per triangle.

If enabled, will generate triangle strips for the whole mesh

RebuildNormals false If enabled, will ignore the normals stored in the original mesh, and rebuild them from scratch using mesh geometry.
Mesh importer: 'Geometry' settings


The Animation node contains the animation-related properties (both skeletal and non-skeletal)

Field name Default value Description
ImportAnimation false If enabled, will import animations
ImportSkeleton false If enabled, will import the skeleton and vertex skinning information (required for skeletal animations)
UseAnimFrameBind false Define the bind pose as the first frame of the animation
OptimizeForCPUSkinning false Enable this for faster CPU skinning. Will reorder vertices in the mesh. Do not check this if you expect the vertices to be in a precise order.
MaxBonesPerVertex 8 Maximum number of bones per vertex, cannot be greater than 256
BoneWeightDiscardTreshold 0.0 Treshold below which vertex bone weights will be discarded and set to zero
RemapToZero true When enabled, forces the first frame of the animation to t=0
Mesh importer: 'Animation' settings


The Kd-Tree node is an advanced configuration category allows you to tweak the Kd-Tree generation. (An acceleration structure used at runtime for mesh intersection, projection, and some other algorithms)

Field name Default value Description
WriteKdTree true If disabled, will not build the KdTree. Note: if you don't build the KdTree, you won't be able to use some specific features such as ray intersections or projection on this mesh.
KdTree_Compression <FastLZ> Controls how the KdTree gets compressed
  • None : No compression
  • FastLZ : Use the FastLZ Algorithm (you must make sure the runtime SDK your company has licensed contains the FastLZ decompressor)
  • BZip : Use the BZ2 Algorithm (you must make sure the runtime SDK your company has licensed contains the BZ2 decompressor)
KdTree_FastBuild false If enabled, will use a much simpler, lower quality, and faster KdTree construction algorithm
KdTree_MaxNodeVerticesBeforeSplit 15 (Advanced) Maximum number of vertices a node is allowed to contain before being subdivided.
KdTree_MaxDepth 32 (Advanced) Maximum depth the KdTree branches are allowed to reach.
KdTree_MinNodeExtent 1.0e-6 (Advanced) Smallest node size before no more splits happen.
KdTree_NodeTraversalCost 0.1 (Advanced) Heuristic weight : abstract cost of traversing a node at runtime
KdTree_TriangleIntersectionCost 1.0 (Advanced) Heuristic weight : abstract cost of processing a mesh triangle at runtime
Mesh importer: 'KdTree' settings

Building tetrahedral meshes

NewIcon.png v1.10.0 / Experimental Tetrahedral mesh information is required if you want to use your mesh in a volume sampler

The tetrahedron-building algorithm is a complex beast, and is still in a highly experimental state, Therefore, the current implementation hasn't been optimized at all, and until we find a proper, stable, and reliable way to build tetrahedral indices, it won't be exposed into any "official" settings.

Also, the current algorithm won't (and can't) work with any mesh that does not fit the following criteria:

  • closed, watertight envelope, no holes
  • no mesh parts with non-manifold topology see also here and here.
  • no t-junctions, only clean topology
  • no intersecting triangles (watch out on character meshes, even with clean topology, such intersections might be found, around the armpits for example. It doesn't matter if the mesh is animated, and penetration occurs during animation, only the base pose from which the tetrahedrons will be built matters)
  • no mesh above 10 000 triangles (this limit will be removed in future versions, and it's not a limit per-se, but the current building algorithm becomes exponentially slower. The runtime sampling is not affected and stays fast no matter the number of tetrahedrons)

The runtime is able to sample tetra-meshes efficiently, and the volume sampling runs smoothly, so, if you really want to build the volume sampling structures, here are the steps to follow:

1. click in the mesh importer viewport, and hit the 'T' key

This will startup the volume builder (it might take a while and the editor might appear to freeze. Then, you should see the following appear in the viewport:

Tetrahedral build : Enabling tetra builder

The debug display shows:

  • the original mesh on the left (as usual)
  • the output volume mesh on the middle
  • the source triangle mesh on the right

Tetrahedral build : Debug display

2. Consume the initial mesh and procude tetras

Hit the 'RIGHT ARROW' key to produce one tetrahedron at a time.
Hit the 'LEFT ARROW' to toggle auto-repeat on the left-arrow key
Hit the 'UP ARROW' key to launch continuous production, hit same key again to pause it, re-hit to resume
When you're satisfied with what's been produced, pause the tetra production.

Tetrahedral build : Consuming tetras

As the original surface is consumed and tetras are produced, the debug display on the left hand side will show an increasing number of tetras, and the original volume vs tetrahedral volume.

The goal of the tetrahedral build is to reach a pretty close match of the original volume. But it's not always possible, so at some points you might see the 'New Vertices' count increase. These are additional vertices that were not in the original mesh. Usually this count becomes greater than zero at the end of the build, when the tetrahedrizer is left with an intricate remaining triangle surface it doesn't understand or know how to tetrahedrize, it will then try to insert new vertices somewhere on the existing surface, by interpolating existing vertices, and see if it helps.

You typically want to keep this count as low as possible (less than 5-10% of the original mesh verts), especially if the tetras volume is already really close to the original mesh's volume.

Tetrahedral build stats

3. Hit the 'S' key to save the tetrahedral indices in the .pkmm mesh file

IMPORTANT: As this is a manual-only build process, if you re-import or re-build your mesh, you will loose the tetra indices, and will have to rebuild them manually again ! This can happen when baking your effect files if you check the "Full Rebake" option, which will overwrite the .pkmm in the editor's cache folder, and perform a full reimport of the FBX mesh, loosing the manually built volume information in the process.

This is pretty painful, but keep in mind it's an experimental feature we decided to give access to so you can play with it and test the early version, if you need volume mesh sampling.
All that will be improved in upcoming releases.

4. Have fun with the volume sampler :)

Volume samping ftw!