Lightmap Baker By EnG

Easy to use library for baking Lightmaps on CPU.

---

---

This repository provides a C-based DLL library for baking lightmaps from 3D scene geometry. It takes an OBJ file as input, along with light definitions, and generates a lightmap texture. The library is designed to be callable from Python using ctypes.

Features

• OBJ Model Loading: Supports loading 3D models from .obj files. Requires models to have UV coordinates for lightmap generation.
• UV Rasterization: Rasterizes triangle UV coordinates to generate a basis for the lightmap.
• Ray Tracing for Lighting: Implements basic ray tracing for calculating direct lighting and soft shadows.
• Point and Directional Lights: Supports both point lights and directional lights with customizable color, intensity, and position/direction.
• Soft Shadows: Utilizes shadow sampling for softer shadow edges, configurable with the number of samples and light radius.
• Simple Occlusion Culling: Uses Axis-Aligned Bounding Boxes (AABBs) for basic intersection acceleration during ray tracing.
• DLL Export: Compiled as a dynamic link library (DLL) for cross-language integration, particularly with Python.

Getting Started

Prerequisites

• A C compiler (e.g., GCC, Clang, MSVC) capable of creating shared libraries.
• Python 3.x installed.
• NumPy (pip install numpy) for numerical operations in Python.
• Pillow (pip install Pillow) for image saving in Python.
• The .obj file for your scene, must contain valid UV coordinates.

Building the DLL

1. Locate the C source file: The C source code is typically found in a native/ directory (e.g., native/lightmap_baker.c).

2. Compile the C code: Use your C compiler to compile the source file into a shared library. The commands below are examples; adjust them based on your operating system and compiler.

   Linux (GCC):

   gcc -shared -fPIC -O3 -o lightmap_baker.so native/lightmap_baker.c -lm

   Windows (MinGW GCC):

   gcc -shared -O3 -o lightmap_baker.dll native/lightmap_baker.c -lm

   (For MSVC, you would use cl /LD /O2 native/lightmap_baker.c /link /out:lightmap_baker.dll /IMLIB and ensure necessary libraries are linked)

   macOS (Clang):

   clang -shared -fPIC -O3 -o lightmap_baker.dylib native/lightmap_baker.c -lm

   Ensure the compiled library (.so, .dll, or .dylib) is placed in the root directory of this repository or in a location where your Python script can find it.

Using the Library (Python)

The provided Python script main.py demonstrates how to load the compiled DLL and call the light baking process.

Example Workflow:

1. Place your .obj file in a suitable location.

2. Compile the C code into a shared library and place it in the repository's root directory.

3. Run the Python script from the repository's root directory:

   python main.py --input path/to/your/scene.obj --out_dir ./output --size 256 --shadow_samples 16 --light_radius 0.2 --light point,2,4,2,1,1,1,10 --light directional,-1,-1,-1,1,0.95,0.8,1

   • --input: Path to your .obj file.

   • --out_dir: Directory to save the generated lightmap.

   • --size: Resolution of the lightmap (e.g., 256 for 256x256).

   • --shadow_samples: Number of samples for soft shadows (higher = softer, slower).

   • --light_radius: Radius for point lights for soft shadow calculation.

   • --light: Define lights. Multiple --light arguments can be used.

     • Point Light format: point,x,y,z,r,g,b,intensity
       • Example: point,2.0,4.0,2.0,1.0,1.0,1.0,10.0
     • Directional Light format: directional,dx,dy,dz,r,g,b,intensity
       • Example: directional,-1.0,-1.0,-1.0,1.0,0.95,0.8,1.0

C API Reference

The primary function exported by the DLL is:

void bake_lightmap(
    const char *obj_path,
    float *out_image,
    int size,
    int shadow_samples,
    float light_radius,
    Light *lights,
    int light_count
);

Parameters:

• obj_path (const char*): Path to the .obj file containing the scene geometry.
• out_image (float*): A pointer to a float array where the baked lightmap data will be stored. Expected format is size * size * 3 floats (R, G, B channels). The output values are in the range [0.0, 1.0].
• size (int): The resolution of the lightmap (e.g., 256 for a 256x256 texture).
• shadow_samples (int): The number of samples to use for calculating soft shadows. Higher values result in softer shadows but take longer to compute.
• light_radius (float): The radius of the light source for soft shadows. This parameter is primarily used for point lights (type=0).
• lights (Light*): A pointer to an array of Light structures defining the lights in the scene.
• light_count (int): The number of lights in the lights array.

Light Structure Fields:

• pos (Vec3): Position of the light (used for point lights).
• dir (Vec3): Direction of the light (used for directional lights; should ideally be normalized).
• color (Vec3): RGB color of the light (values typically between 0.0 and 1.0).
• intensity (float): Brightness of the light.
• type (int): Type of the light:
  • 0: Point light.
  • 1: Directional light.

Vec3 Structure Fields:

• x, y, z (float): Components of the 3D vector.

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs or feature requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.