Houdini Folder-Based File Importer

01 The Problem — File Merge SOP at Scale

Houdini's built-in File Merge SOP handles geometry import through a manually configured file list or a single glob pattern. This works well for a handful of files in a flat directory. It breaks down in three specific ways as asset sets grow:

02 How the Tool Works — Directory Traversal

The tool uses Python's os.walk to recursively traverse a root directory. For each subdirectory, it collects geometry files matching a configurable format filter, imports them via Houdini's Python SOP API, and writes primitive group attributes preserving the folder name as the group identifier.

Python Implementation Pattern

import os
import hou

node    = hou.pwd()
geo     = node.geometry()

root_dir    = node.parm('root_directory').eval()
formats     = node.parm('file_formats').eval().split()   # e.g. ['.obj', '.fbx']
merge_geo   = hou.Geometry()

for dirpath, dirnames, filenames in os.walk(root_dir):
    # Derive group name from folder path relative to root
    rel_path   = os.path.relpath(dirpath, root_dir)
    # Sanitize: replace path separators and spaces with underscores
    group_name = rel_path.replace(os.sep, '_').replace(' ', '_').replace('.', '')
    if group_name == '':
        group_name = 'root'

    for fname in sorted(filenames):
        ext = os.path.splitext(fname)[1].lower()
        if ext not in formats:
            continue   # format filter — skip unwanted extensions

        fpath = os.path.join(dirpath, fname)

        # Import geometry file into temporary geometry object
        file_geo = hou.Geometry()
        file_geo.loadFromFile(fpath)

        # Tag all imported primitives with folder-derived group attribute
        grp = file_geo.findPrimGroup(group_name)
        if grp is None:
            grp = file_geo.createPrimGroup(group_name)
        for prim in file_geo.prims():
            grp.add(prim)

        # Also write string attribute for downstream material / LOD logic
        s_attr = file_geo.findPrimAttrib('folder_group')
        if s_attr is None:
            s_attr = file_geo.addAttrib(
                hou.attribType.Prim, 'folder_group', '')
        for prim in file_geo.prims():
            prim.setAttribValue('folder_group', group_name)

        merge_geo.merge(file_geo)

geo.merge(merge_geo)

Folder → Group Mapping

The folder hierarchy maps directly to Houdini primitive groups. A directory structure like the one below produces distinct, addressable groups in the merged geometry:

assets/
  vehicles/
    car_body.obj
    car_wheels.obj
  environment/
    road.obj
    barriers.obj

Primitive groups:
  vehicles       → car_body + car_wheels prims
  environment    → road + barriers prims

String attribute 'folder_group':
  "vehicles"     → per-prim on car geometry
  "environment"  → per-prim on env geometry

03 Local Transform Correction

A common issue with multi-source geometry imports is axis orientation mismatch. OBJ files from different DCCs use different up-axis conventions — Maya exports Y-up, Blender exports Z-up by default, 3ds Max uses Z-up. FBX carries transform metadata but it is frequently ignored or misread by Houdini's importer depending on version and export settings.

The result is that geometries arrive with correct topology but wrong local rotation or scale. In a flat import this must be corrected after the merge — which is ambiguous when multiple sources with different conventions are merged into one geometry stream.

Gallery 03: Local rotation correction — before (left) and after (right). Per-file transform applied before merge preserves correct orientation per asset source.

The tool applies transform correction per imported file, before merging into the combined geometry stream. This means different files in the same import batch can receive different corrections — a Y-up OBJ and a Z-up FBX in the same directory both arrive correctly oriented without post-merge ambiguity.

04 Performance Comparison

In a representative test — 3 OBJ files totalling 1,387,781 polygons — the tool was benchmarked against the equivalent manual File Merge SOP setup:

Fig 04: Benchmark output — 2.396 s (Folder Importer) vs 2.625 s (File Merge SOP) on identical geometry.

05 Pipeline Position & Use Cases

The tool sits at the ingestion stage of a Houdini pipeline — immediately after receiving external assets, before any procedural processing. Its output is a single merged geometry stream with group and attribute metadata intact, ready for any downstream SOP network.