DOCSEARCHbyAlgolia
Submit Docs

Foam: Automated Mesh Simplification Framework

repository·master·Indexed 41 days ago

https://github.com/commalab/foam

Foam is a framework for creating spherical approximations of robot geometries from URDF specifications and mesh files (.DAE, .STL, .OBJ). It replaces complex collision geometries with spherical primitives to reduce computational load and improve simulator compatibility. Version 0.1.1 includes tools for generating spheres via various algorithms (medial, spawn, grid, hubbard, octree), visualizing approximations, and managing environments via pixi or Docker.

Tokens
5.7K
Snippets
20
Records
25
Agent score
52%

What's inside Foam

  1. Build the foam Docker image

    master

    To build the foam Docker image, first enable DOCKER_BUILDKIT to speed up the build process and allow for secret utilization. Then, use the docker build command from the directory containing the Dockerfile.

    Enable BuildKit:

    • Windows (PowerShell): $env:DOCKER_BUILDKIT = "1"
    • Linux/macOS: export DOCKER_BUILDKIT=1

    Build Command: Run the build command with the tag foam-image.

    # Linux/macOS
export DOCKER_BUILDKIT=1
docker build -t foam-image .

  2. Install Foam natively on Linux/WSL

    master

    To build Foam from source on Linux or WSL, ensure you have python3.11 and cmake 3.29 installed. Follow these steps to clone the repository, build with Ninja, and install Python requirements:

    1. Clone the repository recursively to include submodules.
    2. Configure the build directory using CMake and the Ninja generator.
    3. Build the project.
    4. Install the necessary Python dependencies.
    git clone --recursive https://github.com/CoMMALab/foam.git
cd foam
cmake -Bbuild -GNinja .
cmake --build build/
pip install -r requirements.txt

  3. Run and manage the foam Docker container

    master

    Once the image is built, you can run the container and mount your current working directory to /foam inside the container to allow for development and file persistence.

    Run a new container: Use docker run with the -it flag for interactive mode, -v to mount your current directory, and --name to assign the name foam.

    Manage existing containers:

    • Re-enter a running container: Use docker exec to open a bash shell.
    • Start/Stop: Use docker start and docker stop to manage the lifecycle of the container named foam.
    # Run the container (mounts current directory to /foam)
docker run -it -v "$(pwd)/:/foam" --name=foam foam-image

# Re-enter the container
docker exec -it foam /bin/bash

# Start and stop the container
docker start foam
docker stop foam

  4. Compile and test the Smallest Enclosing Ball code

    master

    To compile the code and run the provided test driver, use the included Makefile.

    Files involved:

    • ball.h and ball.cc: Core logic.
    • tball.cc: A driver test program that reads input from a file and prints the output.
    • Makefile: Used to compile the tball executable.

    Testing with sample files: After compiling, you can test the tball executable using the provided sample files:

    • 1.tst: A sample file for testing on points.
    • 2.tst: A sample file for testing on balls.
    # To compile the test driver
make

# To run the test driver on points
./tball 1.tst

# To run the test driver on balls
./tball 2.tst

  6. Overview of Sphere Tree Construction Algorithms

    master

    The spheretree toolkit provides various algorithms for constructing sphere-tree representations of polygonal models, primarily used for interruptible collision detection.

    Key algorithms include:

    • Octree: The simplest and fastest. Divides a bounding cube into 8 sub-cubes recursively. Can create either a shell or a solid representation.
    • Grid: An extension of Octree that allows non-2x2x2 divisions (any grid dimensions) and optimizes orientation/size to minimize approximation error.
    • Hubbard: Uses a medial axis approximation to create tight-fitting sphere-trees.
    • Merge: Reduces the number of spheres in a medial-axis approximation by successively merging pairs.
    • Burst: An iterative medial-axis algorithm that improves error distribution by 'bursting' (removing) a sphere and using neighbors to fill gaps.
    • Expand: Distributes error evenly by growing spheres so they hang over the surface by a consistent 'stand-off distance'.
    • Spawn: Uses local optimization instead of the medial axis to find sphere locations that cover the most object area.
    • Combined: A hybrid approach that tries multiple algorithms (typically Merge and Expand) for each set of spheres and selects the one with the lowest error.

  7. Generate the vec.h macro library

    master

    The module uses a high-performance linear algebra library called vec.h, which is implemented as a set of C macros to avoid function call overhead and remain type-independent.

    To use it, you must generate the header using the vec_h.c program. The program requires a single integer argument specifying the maximum dimension for vectors and matrices.

    Command:

    ./vec_h <dimension>

    This will output a vec.h file containing macros for N-dimensional determinants, cross products, and other standard vector/matrix operations. The resulting macros support any type that is indexable and assignment-compatible (including all integer/floating point types and C++ arithmetic classes).

    # Example: Generate vec.h for up to 3-dimensional vectors
./vec_h 3

  8. Build the spheretree programs on UNIX

    master

    To compile the command line programs in a UNIX-like environment, use the provided configure script and make.

    1. Navigate to the extracted archive directory.
    2. Run ./configure.
    3. Run make.

    Compiled command line programs will be located in the src directory.

    ./configure
make

  9. Perform complete polyhedron-cube intersection testing

    master

    The intersection routines in this module test for intersections with points, edges, and surfaces, but not volumes. If no intersection is reported, the volume of the polyhedron might still contain the entire unit box. To perform a complete test, you must check if the polyhedron contains the origin (the center of the unit cube).

    Complete Test Algorithm (Pseudo-code):

    switch(trivial_vertex_tests(verts))
    {
        case  1: return true  /* trivial accept: all vertices are inside or on the cube */
        case  0: return false /* trivial reject: all vertices are outside a single plane */
        case -1: 
                 /* Ambiguous case: perform detailed checks */
                 for each edge
                     if(segment_intersects_cube(edge))
                         return true
                 for each face
                     if(fast_polygon_intersects_cube(..., true, true))
                         return true
                 /* Final check: does the polyhedron volume contain the cube center? */
                 return polyhedra_contains_point(polyhedra, origin)
    }
    switch(trivial_vertex_tests(verts))
    {
        case  1: return true  /* trivial accept */
        case  0: return false /* trivial reject */
        case -1: for each edge
                     if(segment_intersects_cube(edge))
                         return true
                 for each face
		     if(fast_polygon_intersects_cube(..., true, true))
                         return true
                 return polyhedra_contains_point(polyhedra, origin)
    }

  10. Use the EnclosingBall function to calculate smallest enclosing balls

    master

    The EnclosingBall function is the primary entry point for calculating the smallest enclosing ball of a set of points or balls.

    Key Details:

    • Header File: Detailed documentation of the function's parameters is located in ball.h.
    • Implementation: The core logic is implemented in ball.cc.
    • Dependencies: The function requires a Singular Value Decomposition (SVD) implementation. The original distribution is designed to work with the Numerical Recipes version of SVD.
    • Numerical Note: The implementation assumes array indexing starts at 1 (consistent with Numerical Recipes), rather than the standard C/C++ 0-based indexing. If you switch to a different SVD package, you will likely need to modify the code to accommodate 0-based indexing.
    • Precision Warning: In high-dimensional spaces (e.g., 36D or 100D), you may encounter numerical issues such as non-convergence in SVD routines or radius inaccuracies of up to 1.5% due to roundoff errors. Using double precision arithmetic or a more robust SVD package is recommended for high-dimensional data.

  11. Visualize spheres and meshes

    master

    Use the visualize_spheres.py script to overlay the generated spherical approximation on top of the original mesh for verification.

    Arguments:

    • <mesh>: Path to the original mesh file.
    • <spheres>: (Optional) Path to the generated spheres file to visualize on top of the mesh.
    • --depth <depth>: (Optional) Specify the sphere level to visualize.
    python visualize_spheres.py <mesh> <spheres> --depth <depth>

  12. Generate spherical approximations from a mesh

    master

    Use the generate_spheres.py script to generate a JSON file representing a spherical approximation of a single mesh file.

    Supported Mesh Formats: .DAE, .STL, and .OBJ.

    Arguments:

    • <mesh>: Path to the input mesh file.
    • --method <algorithm>: The spherization algorithm to use. Defaults to medial. Available options: medial, spawn, grid, hubbard, and octree.
    • --depth <depth>: Controls the sphere generation process depth.
    • --branch <branching factor>: Controls the branching factor of the sphere tree.
    • --manifold-leaves <leaves>: Controls mesh correction on invalid (non-manifold) meshes.
    python generate_spheres.py <mesh> --method <algorithm> --depth <depth> --branch <branching factor> --manifold-leaves <leaves>