obj2bsp

A Python tool that converts Wavefront .obj file into a simple text-based .bsp format representing a Binary Space Partitioning (BSP) tree, which can be easily integrated into other applications (e.g. video games).

Usage

python obj2bsp.py [-o OUTPUT] [--visualize] input.obj

positional arguments:
  input                Input .obj file

options:
  -o, --output OUTPUT  Output .bsp file
  --visualize          Generate a Mermaid diagram of the BSP tree

Note: BSP tree assumes a closed volume. If your .obj model is not sealed correctly, it may cause leaks

.bsp File Formal

The generated .bsp file stores one BSP node per line:

<plane_nx> <plane_ny> <plane_nz> <plane_d> <front_index> <back_index>
...

• plane_n* / plane_d - plane normal (xyz) and signed distance from the origin
• front_index / back_index - indices of child nodes (0 indicates a leaf)

Point-in-BSP Test

To determine whether a point lies inside the BSP volume you can implement a function like this:

def is_point_inside_bsp(bsp_nodes, point):
    i = 0  # start from the root node
    while True:
        node = bsp_nodes[i]

        if distance_point_to_plane(node.plane, point) >= 0:
            i = node.front
            if i == 0:
                return True  # inside
        else:
            i = node.back
            if i == 0:
                return False  # outside