### Define Custom Command to Generate Build Headers Pre-Build (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Defines a custom command that runs before a target is built. This example uses a CMake script (`PicoGKBuildHeader.cmake`) to generate build headers, incorporating library version information.

```cmake
add_custom_command(
    TARGET ${LIB_NAME} PRE_BUILD
    COMMAND ${CMAKE_COMMAND} -E echo "Creating build headers..."
    COMMAND ${CMAKE_COMMAND} 	-DAPIDIR=${CMAKE_CURRENT_SOURCE_DIR}/API 
    							-DLIB_VERSION=${LIB_VERSION}
    							-DLIB_NAME=${LIB_NAME}
    							-P ${CMAKE_CURRENT_SOURCE_DIR}/CMake_Utils/PicoGKBuildHeader.cmake
    COMMENT "Create build headers"
)
```

--------------------------------

### Define Custom Command to Copy Files Post-Build (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Creates a custom command that executes after a target is built. This example copies header files and library files to a specified 'Dist' directory for distribution.

```cmake
add_custom_command(
    TARGET ${LIB_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_directory
        ${CMAKE_CURRENT_SOURCE_DIR}/API
        ${CMAKE_CURRENT_SOURCE_DIR}/Dist
    COMMENT "Copying header files to Dist folder"
)

add_custom_command(
    TARGET ${LIB_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_directory
        ${CMAKE_BINARY_DIR}/lib
        ${CMAKE_CURRENT_SOURCE_DIR}/Dist
    COMMENT "Copying library files to Dist folder"
)
```

--------------------------------

### Set Target Properties for Library Output Directory (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Configures properties for a target, such as the output directory for the library. This example sets the library output directory to be different for Debug and Release builds.

```cmake
set_target_properties(${LIB_NAME} PROPERTIES

LIBRARY_OUTPUT_DIRECTORY $<IF:$<CONFIG:Debug>,${CMAKE_BINARY_DIR}/lib,${CMAKE_BINARY_DIR}/lib>)
```

--------------------------------

### Voxel Operations and Boolean Geometry

Source: https://context7.com/leap71/picogkruntime/llms.txt

Provides examples of creating voxel objects, rendering meshes into voxels, performing boolean operations (union, difference, intersection), offsetting, applying filters (Gaussian, Median, Mean), and calculating properties like volume and bounding box. It also shows how to test if a point is inside the voxel geometry. Requires functions from the PicoGK library for voxel manipulation. Ensure to destroy voxel objects when no longer needed.

```c
// Create voxel objects
PKVOXELS hVoxels1 = Voxels_hCreate();
PKVOXELS hVoxels2 = Voxels_hCreate();

// Render a mesh into voxels
PKMESH hMesh = Mesh_hCreate();
// ... add mesh data ...
Voxels_RenderMesh(hVoxels1, hMesh);

// Create a copy
PKVOXELS hVoxelsCopy = Voxels_hCreateCopy(hVoxels1);

// Perform boolean operations
Voxels_BoolAdd(hVoxels1, hVoxels2);        // Union
Voxels_BoolSubtract(hVoxels1, hVoxels2);   // Difference
Voxels_BoolIntersect(hVoxels1, hVoxels2);  // Intersection

// Offset operations (positive = expand, negative = shrink)
Voxels_Offset(hVoxels1, 2.0f);  // Expand by 2mm

// Apply filters
Voxels_Gaussian(hVoxels1, 1.0f);  // Smooth with gaussian
Voxels_Median(hVoxels1, 1.0f);    // Median filter
Voxels_Mean(hVoxels1, 1.0f);      // Mean filter

// Calculate properties
float volume;
PKBBox3 bbox;
Voxels_CalculateProperties(hVoxels1, &volume, &bbox);
printf("Volume: %.2f mm³\n", volume);

// Test point inside/outside
PKVector3 testPoint = {5.0f, 5.0f, 5.0f};
bool isInside = Voxels_bIsInside(hVoxels1, &testPoint);
printf("Point is %s\n", isInside ? "inside" : "outside");

// Clean up
Voxels_Destroy(hVoxels1);
Voxels_Destroy(hVoxels2);
Voxels_Destroy(hVoxelsCopy);
Mesh_Destroy(hMesh);
```

--------------------------------

### Create Interactive 3D Viewer with Callbacks in C

Source: https://context7.com/leap71/picogkruntime/llms.txt

Demonstrates creating an interactive 3D viewer window using the PicoGK C API. It includes setting up various callback functions for information, updates, keyboard input, mouse events, and window resizing. The viewer can load meshes and polylines, manage group visibility and materials, and save screenshots. Proper cleanup of resources is also shown.

```c
// Define callback functions
void InfoCallback(const char* message, bool isFatal) {
    printf("[%s] %s\n", isFatal ? "ERROR" : "INFO", message);
}

void UpdateCallback(PKVIEWER viewer, const PKVector2* viewport,
                   PKColorFloat* background, PKMatrix4x4* mvp,
                   PKMatrix4x4* modelTransform, PKMatrix4x4* staticTransform,
                   PKVector3* eyePos, PKVector3* eyeStatic) {
    // Set background color
    background->R = 0.2f;
    background->G = 0.2f;
    background->B = 0.3f;
    background->A = 1.0f;

    // Update camera matrices as needed
    // ...
}

void KeyPressedCallback(PKVIEWER viewer, int32_t key, int32_t scancode,
                       int32_t action, int32_t mods) {
    if (key == 256 && action == 1) {  // ESC pressed
        Viewer_RequestClose(viewer);
    }
}

void MouseMovedCallback(PKVIEWER viewer, const PKVector2* pos) {
    // Handle mouse movement
}

void MouseButtonCallback(PKVIEWER viewer, int32_t button, int32_t action,
                        int32_t mods, const PKVector2* pos) {
    // Handle mouse clicks
}

void ScrollWheelCallback(PKVIEWER viewer, const PKVector2* offset,
                        const PKVector2* pos) {
    // Handle scroll wheel
}

void WindowSizeCallback(PKVIEWER viewer, const PKVector2* size) {
    printf("Window resized to %.0fx%.0f\n", size->X, size->Y);
}

// Create viewer window
PKVector2 windowSize = {1920.0f, 1080.0f};
PKVIEWER hViewer = Viewer_hCreate(
    "PicoGK Viewer",
    &windowSize,
    InfoCallback,
    UpdateCallback,
    KeyPressedCallback,
    MouseMovedCallback,
    MouseButtonCallback,
    ScrollWheelCallback,
    WindowSizeCallback
);

if (!Viewer_bIsValid(hViewer)) {
    fprintf(stderr, "Failed to create viewer\n");
    return 1;
}

// Load lighting textures (DDS format)
// Viewer_bLoadLightSetup(hViewer, diffuseData, diffuseSize,
//                        specularData, specularSize);

// Add mesh to viewer
PKMESH hMesh = Mesh_hCreate();
// ... populate mesh ...
Viewer_AddMesh(hViewer, 0, hMesh);  // group ID 0

// Add polyline
PKColorFloat green = {0.0f, 1.0f, 0.0f, 1.0f};
PKPOLYLINE hLine = PolyLine_hCreate(&green);
// ... add vertices ...
Viewer_AddPolyLine(hViewer, 0, hLine);

// Set group properties
Viewer_SetGroupVisible(hViewer, 0, true);
Viewer_SetGroupStatic(hViewer, 0, false);

PKColorFloat matColor = {0.8f, 0.8f, 0.8f, 1.0f};
Viewer_SetGroupMaterial(hViewer, 0, &matColor, 0.5f, 0.5f);  // metallic, roughness

// Request screen shot
Viewer_RequestScreenShot(hViewer, "/path/to/screenshot.tga");

// Trigger re-render
Viewer_RequestUpdate(hViewer);

// Event loop
while (Viewer_bPoll(hViewer)) {
    // Process events
}

// Clean up
Viewer_RemoveMesh(hViewer, hMesh);
Viewer_RemovePolyLine(hViewer, hLine);
Viewer_Destroy(hViewer);
Mesh_Destroy(hMesh);
PolyLine_Destroy(hLine);

```

--------------------------------

### Save and Load VDB Files with C

Source: https://context7.com/leap71/picogkruntime/llms.txt

Demonstrates how to create, populate, save, and load VDB files containing voxel, scalar, and vector fields using the C API. It covers adding fields, setting values, querying file contents, and retrieving data. Proper resource management with destroy functions is emphasized.

```c
// Create VDB file container
PKVDBFILE hVdbFile = VdbFile_hCreate();

// Create and add voxel geometry
PKVOXELS hVoxels = Voxels_hCreate();
// ... populate voxels ...
int32_t voxelIdx = VdbFile_nAddVoxels(hVdbFile, "MainGeometry", hVoxels);

// Create and add scalar field
PKSCALARFIELD hScalarField = ScalarField_hCreate();
PKVector3 pos = {10.0f, 10.0f, 10.0f};
ScalarField_SetValue(hScalarField, &pos, 42.5f);
int32_t scalarIdx = VdbFile_nAddScalarField(hVdbFile, "Temperature", hScalarField);

// Create and add vector field
PKVECTORFIELD hVectorField = VectorField_hCreate();
PKVector3 vecValue = {1.0f, 2.0f, 3.0f};
VectorField_SetValue(hVectorField, &pos, &vecValue);
int32_t vectorIdx = VdbFile_nAddVectorField(hVdbFile, "Velocity", hVectorField);

// Save to file
if (!VdbFile_bSaveToFile(hVdbFile, "/path/to/output.vdb")) {
    fprintf(stderr, "Failed to save VDB file\n");
}
VdbFile_Destroy(hVdbFile);

// Load from file
PKVDBFILE hVdbRead = VdbFile_hCreateFromFile("/path/to/output.vdb");
if (!VdbFile_bIsValid(hVdbRead)) {
    fprintf(stderr, "Failed to load VDB file\n");
    return 1;
}

// Query file contents
int32_t fieldCount = VdbFile_nFieldCount(hVdbRead);
for (int32_t i = 0; i < fieldCount; i++) {
    char fieldName[PKINFOSTRINGLEN];
    VdbFile_GetFieldName(hVdbRead, i, fieldName);
    int32_t fieldType = VdbFile_nFieldType(hVdbRead, i);
    printf("Field %d: %s (type %d)\n", i, fieldName, fieldType);
}

// Retrieve data
PKVOXELS hLoadedVoxels = VdbFile_hGetVoxels(hVdbRead, voxelIdx);
PKSCALARFIELD hLoadedScalar = VdbFile_hGetScalarField(hVdbRead, scalarIdx);
PKVECTORFIELD hLoadedVector = VdbFile_hGetVectorField(hVdbRead, vectorIdx);

// Clean up
VdbFile_Destroy(hVdbRead);
Voxels_Destroy(hVoxels);
Voxels_Destroy(hLoadedVoxels);
ScalarField_Destroy(hScalarField);
ScalarField_Destroy(hLoadedScalar);
VectorField_Destroy(hVectorField);
VectorField_Destroy(hLoadedVector);

```

--------------------------------

### C: Create and Visualize Colored Polylines

Source: https://context7.com/leap71/picogkruntime/llms.txt

Demonstrates the creation of colored polylines for visualization purposes. Includes adding vertices, querying vertex count and positions, retrieving color, and necessary cleanup.

```c
// Create polyline with color
PKColorFloat red = {1.0f, 0.0f, 0.0f, 1.0f};
PKPOLYLINE hPolyLine = PolyLine_hCreate(&red);

if (!PolyLine_bIsValid(hPolyLine)) {
    fprintf(stderr, "Failed to create polyline\n");
    return 1;
}

// Add vertices to form a path
PKVector3 v1 = {0.0f, 0.0f, 0.0f};
PKVector3 v2 = {10.0f, 10.0f, 0.0f};
PKVector3 v3 = {20.0f, 5.0f, 5.0f};
PKVector3 v4 = {30.0f, 0.0f, 0.0f};

PolyLine_nAddVertex(hPolyLine, &v1);
PolyLine_nAddVertex(hPolyLine, &v2);
PolyLine_nAddVertex(hPolyLine, &v3);
PolyLine_nAddVertex(hPolyLine, &v4);

// Query polyline properties
int32_t vertexCount = PolyLine_nVertexCount(hPolyLine);
printf("PolyLine has %d vertices\n", vertexCount);

// Get vertex position
PKVector3 vertex;
olyLine_GetVertex(hPolyLine, 0, &vertex);
printf("First vertex: (%.2f, %.2f, %.2f)\n", vertex.X, vertex.Y, vertex.Z);

// Get color
PKColorFloat color;
PolyLine_GetColor(hPolyLine, &color);
printf("Color: R=%.2f G=%.2f B=%.2f A=%.2f\n",
       color.R, color.G, color.B, color.A);

// Clean up
PolyLine_Destroy(hPolyLine);

```

--------------------------------

### Initialize PicoGK Runtime Library

Source: https://context7.com/leap71/picogkruntime/llms.txt

Initializes the PicoGK library with a specified voxel size in millimeters. It also provides functions to retrieve library information and convert between millimeter and voxel coordinate systems. Requires the 'PicoGK.h' header.

```c
#include "PicoGK.h"
#include <stdio.h>

int main() {
    // Initialize library with 1.0mm voxel size
    Library_Init(1.0f);

    // Get library information
    char szInfo[PKINFOSTRINGLEN];
    Library_GetName(szInfo);
    printf("Library: %s\n", szInfo);

    Library_GetVersion(szInfo);
    printf("Version: %s\n", szInfo);

    Library_GetBuildInfo(szInfo);
    printf("Build: %s\n", szInfo);

    // Convert between coordinate systems
    PKVector3 vecMm = {10.0f, 20.0f, 30.0f};
    PKVector3 vecVoxels;
    Library_MmToVoxels(&vecMm, &vecVoxels);
    printf("MM to Voxels: (%.2f, %.2f, %.2f)\n",
           vecVoxels.X, vecVoxels.Y, vecVoxels.Z);

    return 0;
}
```

--------------------------------

### Create and Manipulate Triangle Meshes

Source: https://context7.com/leap71/picogkruntime/llms.txt

Demonstrates the creation of a simple triangle mesh, adding vertices and triangles, and querying mesh properties like vertex count, triangle count, and bounding box. It requires functions from the PicoGK library for mesh operations. Remember to destroy the mesh when done.

```c
// Create an empty mesh
PKMESH hMesh = Mesh_hCreate();
if (!Mesh_bIsValid(hMesh)) {
    fprintf(stderr, "Failed to create mesh\n");
    return 1;
}

// Add vertices for a simple triangle
PKVector3 v1 = {0.0f, 0.0f, 0.0f};
PKVector3 v2 = {10.0f, 0.0f, 0.0f};
PKVector3 v3 = {5.0f, 10.0f, 0.0f};

int32_t idx1 = Mesh_nAddVertex(hMesh, &v1);
int32_t idx2 = Mesh_nAddVertex(hMesh, &v2);
int32_t idx3 = Mesh_nAddVertex(hMesh, &v3);

// Create triangle from vertex indices
PKTriangle tri = {idx1, idx2, idx3};
int32_t triIdx = Mesh_nAddTriangle(hMesh, &tri);

// Query mesh properties
int32_t vertexCount = Mesh_nVertexCount(hMesh);
int32_t triangleCount = Mesh_nTriangleCount(hMesh);
printf("Mesh has %d vertices and %d triangles\n", vertexCount, triangleCount);

// Get bounding box
PKBBox3 bbox;
Mesh_GetBoundingBox(hMesh, &bbox);
printf("BBox: min(%.2f, %.2f, %.2f) max(%.2f, %.2f, %.2f)\n",
       bbox.vecMin.X, bbox.vecMin.Y, bbox.vecMin.Z,
       bbox.vecMax.X, bbox.vecMax.Y, bbox.vecMax.Z);

// Clean up
Mesh_Destroy(hMesh);
```

--------------------------------

### C: Create and Manipulate Vector Fields

Source: https://context7.com/leap71/picogkruntime/llms.txt

Demonstrates how to create, set, retrieve, and traverse vector values in a 3D sparse vector field using the PicoGK API. It also shows conversion from voxels and cleanup.

```c
// Create vector field
PKVECTORFIELD hVectorField = VectorField_hCreate();

// Set vector values at positions
PKVector3 pos = {10.0f, 10.0f, 10.0f};
PKVector3 velocity = {1.5f, 2.0f, -0.5f};
VectorField_SetValue(hVectorField, &pos, &velocity);

// Retrieve vector values
PKVector3 retrievedVec;
if (VectorField_bGetValue(hVectorField, &pos, &retrievedVec)) {
    printf("Vector: (%.2f, %.2f, %.2f)\n",
           retrievedVec.X, retrievedVec.Y, retrievedVec.Z);
}

// Create from voxels
PKVOXELS hVoxels = Voxels_hCreate();
// ... populate voxels ...
PKVECTORFIELD hFromVoxels = VectorField_hCreateFromVoxels(hVoxels);

// Build with specific value and threshold
PKVector3 defaultVec = {0.0f, 1.0f, 0.0f};
PKVECTORFIELD hThreshold = VectorField_hBuildFromVoxels(
    hVoxels,
    &defaultVec,
    0.5f  // SDF threshold
);

// Traverse active vectors
void VectorTraverseCallback(const PKVector3* pos, const PKVector3* value) {
    printf("Vector at (%.2f, %.2f, %.2f): (%.2f, %.2f, %.2f)\n",
           pos->X, pos->Y, pos->Z, value->X, value->Y, value->Z);
}

VectorField_TraverseActive(hVectorField, VectorTraverseCallback);

// Remove value
VectorField_RemoveValue(hVectorField, &pos);

// Clean up
VectorField_Destroy(hVectorField);
VectorField_Destroy(hFromVoxels);
VectorField_Destroy(hThreshold);
Voxels_Destroy(hVoxels);

```

--------------------------------

### Manage Scalar Fields with C

Source: https://context7.com/leap71/picogkruntime/llms.txt

Illustrates how to create, set, and retrieve scalar values in 3D space. This includes creating fields from voxel boundaries, building fields with thresholds, traversing active voxels, and extracting 2D slice data for visualization. Memory management is handled via destroy functions.

```c
// Create scalar field
PKSCALARFIELD hField = ScalarField_hCreate();

// Set values at specific positions
PKVector3 pos1 = {10.0f, 10.0f, 10.0f};
PKVector3 pos2 = {20.0f, 20.0f, 20.0f};
ScalarField_SetValue(hField, &pos1, 100.5f);
ScalarField_SetValue(hField, &pos2, 200.75f);

// Retrieve values
float value;
if (ScalarField_bGetValue(hField, &pos1, &value)) {
    printf("Value at position: %.2f\n", value);
}

// Create from voxels boundary
PKVOXELS hVoxels = Voxels_hCreate();
// ... populate voxels ...
PKSCALARFIELD hFromVoxels = ScalarField_hCreateFromVoxels(hVoxels);

// Build field with threshold
PKSCALARFIELD hThreshold = ScalarField_hBuildFromVoxels(
    hVoxels,
    42.0f,    // scalar value to set
    0.5f      // SDF threshold
);

// Traverse active voxels
void TraverseCallback(const PKVector3* pos, float value) {
    printf("Active at (%.2f, %.2f, %.2f): %.2f\n",
           pos->X, pos->Y, pos->Z, value);
}

ScalarField_TraverseActive(hField, TraverseCallback);

// Get slice data for 2D visualization
int32_t xOrigin, yOrigin, zOrigin, xSize, ySize, zSize;
ScalarField_GetVoxelDimensions(hField, &xOrigin, &yOrigin, &zOrigin,
                               &xSize, &ySize, &zSize);

float* sliceBuffer = (float*)malloc(xSize * ySize * sizeof(float));
ScalarField_GetSlice(hField, zOrigin + 10, sliceBuffer);
// ... process slice data ...
free(sliceBuffer);

// Remove value
ScalarField_RemoveValue(hField, &pos1);

// Clean up
ScalarField_Destroy(hField);
ScalarField_Destroy(hFromVoxels);
ScalarField_Destroy(hThreshold);
Voxels_Destroy(hVoxels);

```

--------------------------------

### Create Lattice Structures with Spheres and Beams in C

Source: https://context7.com/leap71/picogkruntime/llms.txt

Generates lattice structures by adding spherical nodes and connecting beams with variable radii and cap types. The lattice is then rendered into voxels and converted to a mesh. Requires PKLATTICE, PKVOXELS, PKMESH, and PKVector3 types.

```c
// Create lattice object
PKLATTICE hLattice = Lattice_hCreate();
if (!Lattice_bIsValid(hLattice)) {
    fprintf(stderr, "Failed to create lattice\n");
    return 1;
}

// Add spherical nodes
PKVector3 node1 = {10.0f, 10.0f, 10.0f};
PKVector3 node2 = {50.0f, 50.0f, 50.0f};
PKVector3 node3 = {90.0f, 10.0f, 10.0f};

Lattice_AddSphere(hLattice, &node1, 2.0f);  // radius 2mm
Lattice_AddSphere(hLattice, &node2, 3.0f);
Lattice_AddSphere(hLattice, &node3, 2.0f);

// Add connecting beams with variable radius
Lattice_AddBeam(hLattice, &node1, &node2, 1.5f, 2.0f, true);  // round cap
Lattice_AddBeam(hLattice, &node2, &node3, 2.0f, 1.5f, false); // flat cap

// Render lattice into voxels
PKVOXELS hVoxels = Voxels_hCreate();
Voxels_RenderLattice(hVoxels, hLattice);

// Convert to mesh
PKMESH hMesh = Mesh_hCreateFromVoxels(hVoxels);

// Clean up
Lattice_Destroy(hLattice);
Voxels_Destroy(hVoxels);
Mesh_Destroy(hMesh);
```

--------------------------------

### C: Manage Metadata for Voxel and Field Objects

Source: https://context7.com/leap71/picogkruntime/llms.txt

Shows how to create, set, query, and retrieve metadata associated with voxel and field objects. Supports string, float, and vector types, along with removal and cleanup.

```c
// Get metadata from voxels
PKVOXELS hVoxels = Voxels_hCreate();
// ... populate voxels ...
PKMETADATA hMeta = Metadata_hFromVoxels(hVoxels);

// Set metadata values
Metadata_SetStringValue(hMeta, "Author", "John Doe");
Metadata_SetFloatValue(hMeta, "Scale", 1.5f);
PKVector3 origin = {0.0f, 0.0f, 0.0f};
Metadata_SetVectorValue(hMeta, "Origin", &origin);

// Query metadata count and names
int32_t count = Metadata_nCount(hMeta);
for (int32_t i = 0; i < count; i++) {
    int32_t nameLen = Metadata_nNameLengthAt(hMeta, i);
    char* name = (char*)malloc(nameLen + 1);

    if (Metadata_bGetNameAt(hMeta, i, name, nameLen + 1)) {
        int32_t type = Metadata_nTypeAt(hMeta, name);
        printf("Metadata[%d]: %s (type %d)\n", i, name, type);
    }
    free(name);
}

// Retrieve values by name
char author[256];
if (Metadata_bGetStringAt(hMeta, "Author", author, sizeof(author))) {
    printf("Author: %s\n", author);
}

float scale;
if (Metadata_bGetFloatAt(hMeta, "Scale", &scale)) {
    printf("Scale: %.2f\n", scale);
}

PKVector3 retrievedOrigin;
if (Metadata_bGetVectorAt(hMeta, "Origin", &retrievedOrigin)) {
    printf("Origin: (%.2f, %.2f, %.2f)\n",
           retrievedOrigin.X, retrievedOrigin.Y, retrievedOrigin.Z);
}

// Remove metadata entry
MetaData_RemoveValue(hMeta, "Author");

// Clean up
Metadata_Destroy(hMeta);
Voxels_Destroy(hVoxels);

```

--------------------------------

### Render Implicit Surfaces using SDFs in C

Source: https://context7.com/leap71/picogkruntime/llms.txt

Defines an SDF for a sphere and renders it into voxels. Supports intersection with other implicit functions and conversion to a mesh. Requires PKVector3, PKBBox3, PKVOXELS, and PKMESH types.

```c
// Define an SDF callback for a sphere
float SphereSDF(const PKVector3* pvec) {
    PKVector3 center = {50.0f, 50.0f, 50.0f};
    float radius = 20.0f;

    float dx = pvec->X - center.X;
    float dy = pvec->Y - center.Y;
    float dz = pvec->Z - center.Z;
    float distance = sqrtf(dx*dx + dy*dy + dz*dz);

    return distance - radius;  // Negative inside, positive outside
}

// Create voxels and render implicit surface
PKVOXELS hVoxels = Voxels_hCreate();

// Define bounding box for rendering
PKBBox3 bbox;
bbox.vecMin.X = 0.0f;
bbox.vecMin.Y = 0.0f;
bbox.vecMin.Z = 0.0f;box.vecMax.X = 100.0f;
bbox.vecMax.Y = 100.0f;
bbox.vecMax.Z = 100.0f;

// Render the implicit surface
Voxels_RenderImplicit(hVoxels, &bbox, SphereSDF);

// Intersect with another implicit function
Voxels_IntersectImplicit(hVoxels, SphereSDF);

// Convert to mesh for visualization or export
PKMESH hMesh = Mesh_hCreateFromVoxels(hVoxels);

Voxels_Destroy(hVoxels);
Mesh_Destroy(hMesh);
```

--------------------------------

### Glob Source Files for Library (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Recursively finds all C++ (.cpp) and C (.c) source files within the 'Source' directory and adds them to the library target. This automates the inclusion of source code.

```cmake
# Add all .cpp and .c files recursively from the Source directory
file(GLOB_RECURSE SOURCES
    "Source/*.cpp"
    "Source/*.c"
)

# Add the sources to the library target
target_sources(${LIB_NAME}
    PRIVATE
    ${SOURCES}
)
```

--------------------------------

### Configure Output Directories (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Sets the output directories for runtime libraries and archives. This helps organize build artifacts for easier management.

```cmake
# Set the output directory for the generated libraries and executables
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/Dist)
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/Lib)
```

--------------------------------

### Add API and Source Header Files (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Finds and adds header files from the 'API' and 'Source' directories to the library target. This ensures that headers are correctly associated with the library for compilation.

```cmake
# Add the API header files to the library target
file(GLOB API_HEADERS "${CMAKE_CURRENT_SOURCE_DIR}/API/*.h")
target_sources(${LIB_NAME} PRIVATE ${API_HEADERS})

# Add the header files from the CPP folder to the library target
file(GLOB CPP_HEADERS "${CMAKE_CURRENT_SOURCE_DIR}/Source/*.h")
target_sources(${LIB_NAME} PRIVATE ${CPP_HEADERS})
```

--------------------------------

### VDB File I/O Operations

Source: https://context7.com/leap71/picogkruntime/llms.txt

This section details how to create, populate, save, load, and query OpenVDB files, which can contain voxel data, scalar fields, and vector fields.

```APIDOC
## VDB File I/O

Save and load voxel data, scalar fields, and vector fields using OpenVDB format.

### Create and Populate VDB File

This involves creating a VDB file container, adding voxel geometry, scalar fields, and vector fields to it.

```c
// Create VDB file container
PKVDBFILE hVdbFile = VdbFile_hCreate();

// Create and add voxel geometry
PKVOXELS hVoxels = Voxels_hCreate();
// ... populate voxels ...
int32_t voxelIdx = VdbFile_nAddVoxels(hVdbFile, "MainGeometry", hVoxels);

// Create and add scalar field
PKSCALARFIELD hScalarField = ScalarField_hCreate();
PKVector3 pos = {10.0f, 10.0f, 10.0f};
ScalarField_SetValue(hScalarField, &pos, 42.5f);
int32_t scalarIdx = VdbFile_nAddScalarField(hVdbFile, "Temperature", hScalarField);

// Create and add vector field
PKVECTORFIELD hVectorField = VectorField_hCreate();
PKVector3 vecValue = {1.0f, 2.0f, 3.0f};
VectorField_SetValue(hVectorField, &pos, &vecValue);
int32_t vectorIdx = VdbFile_nAddVectorField(hVdbFile, "Velocity", hVectorField);
```

### Save VDB File

Saves the contents of a VDB file container to a specified file path.

```c
// Save to file
if (!VdbFile_bSaveToFile(hVdbFile, "/path/to/output.vdb")) {
    fprintf(stderr, "Failed to save VDB file\n");
}
```

### Load VDB File

Loads a VDB file from a specified file path into a VDB file container.

```c
// Load from file
PKVDBFILE hVdbRead = VdbFile_hCreateFromFile("/path/to/output.vdb");
if (!VdbFile_bIsValid(hVdbRead)) {
    fprintf(stderr, "Failed to load VDB file\n");
    return 1;
}
```

### Query VDB File Contents

Retrieves information about the fields (voxels, scalar, vector) stored within a loaded VDB file.

```c
// Query file contents
int32_t fieldCount = VdbFile_nFieldCount(hVdbRead);
for (int32_t i = 0; i < fieldCount; i++) {
    char fieldName[PKINFOSTRINGLEN];
    VdbFile_GetFieldName(hVdbRead, i, fieldName);
    int32_t fieldType = VdbFile_nFieldType(hVdbRead, i);
    printf("Field %d: %s (type %d)\n", i, fieldName, fieldType);
}
```

### Retrieve Data from VDB File

Accesses specific voxel, scalar, or vector field data from a loaded VDB file using their indices.

```c
// Retrieve data
PKVOXELS hLoadedVoxels = VdbFile_hGetVoxels(hVdbRead, voxelIdx);
PKSCALARFIELD hLoadedScalar = VdbFile_hGetScalarField(hVdbRead, scalarIdx);
PKVECTORFIELD hLoadedVector = VdbFile_hGetVectorField(hVdbRead, vectorIdx);
```

### Clean Up VDB Resources

Frees the memory associated with VDB file containers and their contents.

```c
VdbFile_Destroy(hVdbFile);
VdbFile_Destroy(hVdbRead);
```
```

--------------------------------

### Configure Runtime Output Directories per Configuration (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Iterates through different build configurations (Debug, Release) to set specific runtime output directories for executables and libraries. This allows for better organization of build outputs.

```cmake
foreach( OUTPUT_CONFIG ${CMAKE_CONFIGURATION_TYPES} )
  string( TOUPPER ${OUTPUT_CONFIG} OUTPUT_CONFIG )
  set( CMAKE_RUNTIME_OUTPUT_DIRECTORY_${OUTPUT_CONFIG} ${CMAKE_BINARY_DIR}/bin )
  set( CMAKE_LIBRARY_OUTPUT_DIRECTORY_${OUTPUT_CONFIG} ${CMAKE_BINARY_DIR}/lib )
endforeach( OUTPUT_CONFIG CMAKE_CONFIGURATION_TYPES )
```

--------------------------------

### Set Project Version and C++ Standard (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Defines the project version and sets the C++ standard to C++20. This ensures modern C++ features are available and helps in version management.

```cmake
cmake_minimum_required(VERSION 3.25.1)

# Define the version
set(LIB_VERSION_MAJOR 1)
set(LIB_VERSION_MINOR 7)
set(LIB_VERSION_SUBMINOR 1)
set(LIB_VERSION "${LIB_VERSION_MAJOR}.${LIB_VERSION_MINOR}.${LIB_VERSION_SUBMINOR}")

project(PicoGK VERSION ${LIB_VERSION})

# Set the C++ standard to C++20 or higher
set(CMAKE_CXX_STANDARD 20)
```

--------------------------------

### Add Executable Target and Link Libraries (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Defines an executable target and links it with other libraries. This is used to create runnable programs from the project's source code.

```cmake
add_executable(APITests)

target_sources(APITests PRIVATE APITests/main.cpp)

target_link_libraries(APITests PRIVATE ${LIB_NAME})
```

--------------------------------

### Organize Source Files into Virtual Folders (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Uses the `source_group` command to organize source files into virtual folders within the build system, improving project navigation. This is typically used for headers and source files.

```cmake
source_group("PicoGK API" FILES ${API_HEADERS})

source_group("PicoGK Classes" FILES ${CPP_HEADERS})
```

--------------------------------

### Set OpenVDB Static Library Runtime (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Ensures the OpenVDB static library uses the correct MSVC runtime library configuration, matching the main project settings for consistency.

```cmake
if( MSVC )
  set_property(TARGET openvdb_static PROPERTY
    MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
endif()
```

--------------------------------

### Link Libraries for Target (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Specifies the libraries that a target should be linked against. This ensures that all necessary dependencies are resolved during the build process.

```cmake
target_link_libraries(${LIB_NAME} openvdb_static glfw )
```

--------------------------------

### Query Voxel Surfaces and Ray Cast in C

Source: https://context7.com/leap71/picogkruntime/llms.txt

Finds the closest point on a voxel surface, retrieves the surface normal, and performs ray casting to find intersection points. Requires PKVOXELS, PKVector3 types and Voxels_bClosestPointOnSurface, Voxels_GetSurfaceNormal, Voxels_bRayCastToSurface functions.

```c
PKVOXELS hVoxels = Voxels_hCreate();
// ... populate voxels ...

// Find closest point on surface
PKVector3 searchPoint = {100.0f, 100.0f, 100.0f};
PKVector3 surfacePoint;

if (Voxels_bClosestPointOnSurface(hVoxels, &searchPoint, &surfacePoint)) {
    printf("Closest surface point: (%.2f, %.2f, %.2f)\n",
           surfacePoint.X, surfacePoint.Y, surfacePoint.Z);

    // Get surface normal at that point
    PKVector3 normal;
    Voxels_GetSurfaceNormal(hVoxels, &surfacePoint, &normal);
    printf("Surface normal: (%.2f, %.2f, %.2f)\n",
           normal.X, normal.Y, normal.Z);
}

// Ray cast to surface
PKVector3 rayOrigin = {0.0f, 0.0f, 0.0f};
PKVector3 rayDirection = {1.0f, 0.0f, 0.0f};  // Unit vector
PKVector3 hitPoint;

if (Voxels_bRayCastToSurface(hVoxels, &rayOrigin, &rayDirection, &hitPoint)) {
    printf("Ray hit surface at: (%.2f, %.2f, %.2f)\n",
           hitPoint.X, hitPoint.Y, hitPoint.Z);
}

Voxels_Destroy(hVoxels);
```

--------------------------------

### Define Library Name based on OS (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Determines the library name based on the operating system. Windows builds append the version number, while Unix-like systems use a standard name.

```cmake
# Define the library name
if( WIN32 )
	set(LIB_NAME "picogk.${LIB_VERSION_MAJOR}.${LIB_VERSION_MINOR}")
else()
	# unix-like systems automatically append version number
	set(LIB_NAME "picogk")
endif()
```

--------------------------------

### Add GLFW Subdirectory (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Includes the GLFW library as a subdirectory. GLFW is commonly used for window creation and input handling in graphics applications, likely for visualization or interaction with PicoGK.

```cmake
#include GLFW

add_subdirectory( ${PICOGK_ROOT_DIR}/GLFW EXCLUDE_FROM_ALL )
```

--------------------------------

### Set Target Properties for Apple Platforms (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Configures specific target properties for Apple platforms (macOS, iOS), including versioning and enabling hardened runtime for improved security.

```cmake
if ( APPLE )
    set_target_properties( ${LIB_NAME} PROPERTIES
        VERSION ${LIB_VERSION}
        SOVERSION "${LIB_VERSION_MAJOR}.${LIB_VERSION_MINOR}.${LIB_VERSION_SUBMINOR}"
        XCODE_ATTRIBUTE_ENABLE_HARDENED_RUNTIME YES
    )
endif()
```

--------------------------------

### Set MSVC Runtime Library (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Configures the MSVC runtime library to use MultiThreaded DLLs for both debug and release builds. This is crucial for compatibility and deployment on Windows.

```cmake
cmake_policy( SET CMP0091 NEW ) #enable MSVC_RUNTIME_LIBRARY property
set( CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL" )
```

--------------------------------

### Set Compiler Flags for Different Configurations (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Configures compiler flags based on the build configuration (e.g., Debug, Release) and the compiler being used (e.g., MSVC). This allows for optimization or debugging features to be enabled selectively.

```cmake
if( MSVC )
    message("Adding bigobj")
    target_compile_options(${LIB_NAME} PRIVATE "/bigobj")
else ()

    target_compile_options(${LIB_NAME} PRIVATE
        $<$<CONFIG:Debug>:-g -O0 -fvisibility=hidden -fvisibility-inlines-hidden>
        $<$<CONFIG:Release>:-O3 -fvisibility=hidden -fvisibility-inlines-hidden>
)
endif()
```

--------------------------------

### Add OpenVDB Subdirectory (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Includes the OpenVDB library as a subdirectory, making its targets available for linking. OpenVDB is a core dependency for PicoGK's computational geometry features.

```cmake
add_subdirectory( ${PICOGK_ROOT_DIR}/openvdb EXCLUDE_FROM_ALL )
```

--------------------------------

### Set Public Include Directories (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Specifies the public include directories for the PicoGK library. Headers in these directories will be visible to targets that link against PicoGK.

```cmake
# Include directories for the library target
target_include_directories(${LIB_NAME}
    PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/API
)
```

--------------------------------

### Add Compiler Definitions for Library Target (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Adds compiler definitions to a specific library target. This is used to conditionally compile code based on build settings, such as defining `PICOGK_BUILD_LIBRARY` for the PicoGK library.

```cmake
target_compile_definitions(${LIB_NAME} PRIVATE PICOGK_BUILD_LIBRARY)
```

--------------------------------

### Set Debug Postfix for Library Name (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Adds a postfix to the library name for debug builds. This is a common convention to distinguish between debug and release versions of a library.

```cmake
set_target_properties(${LIB_NAME} PROPERTIES DEBUG_POSTFIX "d")
```

--------------------------------

### Define PicoGK Shared Library Target (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Defines the main PicoGK library as a shared library target. This is the primary library that will be built and linked against by other applications.

```cmake
# Add library target
add_library(${LIB_NAME} SHARED)
```

--------------------------------

### Scalar Fields API

Source: https://context7.com/leap71/picogkruntime/llms.txt

This section covers the creation, manipulation, and retrieval of scalar fields, which store sparse scalar values in 3D space.

```APIDOC
## Scalar Fields

Store and manipulate sparse scalar values in 3D space.

### Create Scalar Field

Initializes an empty scalar field.

```c
// Create scalar field
PKSCALARFIELD hField = ScalarField_hCreate();
```

### Set Scalar Field Values

Assigns a scalar value to a specific 3D position within the scalar field.

```c
// Set values at specific positions
PKVector3 pos1 = {10.0f, 10.0f, 10.0f};
PKVector3 pos2 = {20.0f, 20.0f, 20.0f};
ScalarField_SetValue(hField, &pos1, 100.5f);
ScalarField_SetValue(hField, &pos2, 200.75f);
```

### Get Scalar Field Values

Retrieves the scalar value at a given 3D position.

```c
// Retrieve values
float value;
if (ScalarField_bGetValue(hField, &pos1, &value)) {
    printf("Value at position: %.2f\n", value);
}
```

### Create Scalar Field from Voxels

Generates a scalar field based on the boundary of voxel data.

```c
// Create from voxels boundary
PKVOXELS hVoxels = Voxels_hCreate();
// ... populate voxels ...
PKSCALARFIELD hFromVoxels = ScalarField_hCreateFromVoxels(hVoxels);
```

### Build Scalar Field from Voxels with Threshold

Constructs a scalar field from voxel data, setting values based on a threshold.

```c
// Build field with threshold
PKSCALARFIELD hThreshold = ScalarField_hBuildFromVoxels(
    hVoxels,
    42.0f,    // scalar value to set
    0.5f      // SDF threshold
);
```

### Traverse Active Scalar Field Voxels

Iterates through all active voxels in the scalar field, applying a callback function to each.

```c
// Traverse active voxels
void TraverseCallback(const PKVector3* pos, float value) {
    printf("Active at (%.2f, %.2f, %.2f): %.2f\n",
           pos->X, pos->Y, pos->Z, value);
}

ScalarField_TraverseActive(hField, TraverseCallback);
```

### Get Scalar Field Slice Data

Extracts a 2D slice of the scalar field at a specified depth for visualization.

```c
// Get slice data for 2D visualization
int32_t xOrigin, yOrigin, zOrigin, xSize, ySize, zSize;
ScalarField_GetVoxelDimensions(hField, &xOrigin, &yOrigin, &zOrigin,
                               &xSize, &ySize, &zSize);

float* sliceBuffer = (float*)malloc(xSize * ySize * sizeof(float));
ScalarField_GetSlice(hField, zOrigin + 10, sliceBuffer);
// ... process slice data ...
free(sliceBuffer);
```

### Remove Scalar Field Value

Deletes a scalar value at a specific 3D position from the scalar field.

```c
// Remove value
ScalarField_RemoveValue(hField, &pos1);
```

### Clean Up Scalar Field Resources

Frees the memory allocated for scalar field objects.

```c
ScalarField_Destroy(hField);
ScalarField_Destroy(hFromVoxels);
ScalarField_Destroy(hThreshold);
// Also ensure Voxels and loaded fields are destroyed if applicable
// Voxels_Destroy(hVoxels);
// ScalarField_Destroy(hLoadedScalar);
```
```

--------------------------------

### Add Debug Build Definition (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Adds a preprocessor definition `DEBUG_BUILD` only for debug configurations. This allows for conditional compilation of code specific to debugging.

```cmake
# Add a preprocessor definition for the debug build
target_compile_definitions(${LIB_NAME} PRIVATE $<$<CONFIG:Debug>:DEBUG_BUILD>)
```

--------------------------------

### Conditional Submodule Update (CMake)

Source: https://github.com/leap71/picogkruntime/blob/main/CMakeLists.txt

Conditionally updates and initializes Git submodules if the PICOGK_UPDATE_SUBMODULES option is enabled. This is useful for ensuring dependencies are up-to-date.

```cmake
# Option to control submodule update and initialization
option(PICOGK_UPDATE_SUBMODULES "Update and initialize Git submodules" OFF)

if(PICOGK_UPDATE_SUBMODULES)
    message(STATUS "Updating and initializing Git submodules...")
    execute_process(
        COMMAND git submodule update --init --recursive --remote
        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
    )
endif()
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.