libvcad_compilers — utilities

Shared helpers for attribute resolution, voxel processing, and I/O.

namespace AttributeResolver

Functions

std::shared_ptr<Node> try_auto_convert(const std::shared_ptr<Node> &root, const std::vector<std::string> &needed)

Attempts a single-step convenience conversion.

Returns a wrapped root with an AttributeModifier if a known conversion exists, or nullptr if no conversion is known.

void validate(const std::shared_ptr<Node> &root, const std::vector<std::string> &required_attributes)

Validates that the root node has all required attributes.

Throws std::runtime_error with a descriptive message listing missing attributes.

class ColorPipeline

#include <color_pipeline.h>

Public Functions

glm::vec4 apply_icc_profile(glm::vec3 rgb) const: Transforms an RGB color (0 to 1) to CMYK using the ICC profile.

std::shared_ptr<ColorPipeline> clone() const: Creates a new instance with its own lcms2 state for thread safety.

ColorPipeline(const std::string &icc_profile = "default")

ColorSampleResult process(const glm::vec4 &rgba_color) const: Full color pipeline: gamma correct -> ICC -> blend -> CMYKW -> stochastic pick.

~ColorPipeline()

Public Static Functions

static glm::vec3 cmyk_to_rgb(const glm::vec4 &cmyk)

static glm::vec3 gamma_correct(glm::vec3 rgb, float gamma = 2.2f)

static std::vector<std::string> get_icc_profiles()

static glm::vec4 rgb_to_cmyk(const glm::vec3 &rgb)

static std::tuple<double, double, double, double, double> rgb_to_cmykw(glm::vec4 rgba)

static void set_icc_resource_path(const std::string &path)

Private Functions

float compute_cmyk_primary_affinity(const glm::vec4 &cmyk) const

Private Members

cmsHTRANSFORM m_color_transform

cmsHPROFILE m_icc_profile

std::string m_icc_profile_name

std::vector<glm::vec4> m_palette

cmsHPROFILE m_srgb_profile

Private Static Attributes

static std::string s_icc_resource_path

struct ColorSampleResult

#include <color_pipeline.h>

Public Members

glm::vec4 color

bool is_active

size_t palette_index

namespace ImageOutput

Functions

std::string setup_output_directory(const std::string &output_directory, const std::string &file_prefix): Creates the output directory if it doesn’t exist and returns the full filename root path (directory + file_prefix).

size_t trim_empty_layers(const std::vector<size_t> &active_voxel_counts, const std::string &filename_root)

Removes empty layers from the beginning and end of a numbered PNG stack.

Renumbers remaining files to start at 0.

Returns:: the number of remaining layers.

bool write_rgba_png(const std::string &path, long width, long height, const std::vector<unsigned char> &rgba_data)

Writes an RGBA image as a PNG file.

Returns:: true on success, false on failure.

class ParallelVoxelLoop

#include <parallel_voxel_loop.h>

Public Types

using LayerCallback = std::function<void(const std::shared_ptr<Node> &thread_local_root, long z_index)>

Public Functions

ParallelVoxelLoop(const std::shared_ptr<Node> &root)

void run(long z_dim, const LayerCallback &layer_fn, const std::atomic<bool> &cancelled, const std::function<void(double)> &progress_callback = nullptr)

Runs parallel_for over [0, z_dim).

For each z, calls layer_fn with a thread-local clone of root. Checks cancellation between layers and reports progress after each layer completes.

Private Members

tbb::task_group_context m_context

std::shared_ptr<Node> m_root

tbb::enumerable_thread_specific<std::shared_ptr<Node>> m_thread_roots

namespace RequiredAttributeCheck

Utilities for enforcing required attribute presence at sampled points during compilation.

All checks throw std::runtime_error with the first failing world-space coordinate when the attribute is absent.

Functions

void require(const std::string &compiler_name, const std::string &attribute_name, const glm::vec3 &world_pos, const std::optional<AttributeSamples> &samples)

Verifies that a required attribute is present in the given samples.

Fast path: returns immediately when the attribute key exists. Throws std::runtime_error with compiler name, attribute name, and world-space XYZ when the attribute is missing.

Parameters:

compiler_name – Human-readable compiler name for the error message.
attribute_name – The attribute key that must be present.
world_pos – The world-space position of the sample point.
samples – The attribute samples at that point (may be nullopt).

void require_fuzzy(const std::shared_ptr<Node> &root, const glm::vec3 &voxel_size, const std::string &compiler_name, const std::string &attribute_name, const glm::vec3 &world_pos, const std::optional<AttributeSamples> &samples)

Same as require() but attempts a fuzzy 3x3x3 neighbor probe before throwing.

Use this for compilers whose sampling grid may land just outside the implicit surface.

Parameters:

root – The prepared node tree (used for neighbor sampling).
voxel_size – The voxel size (determines neighbor offsets).
compiler_name – Human-readable compiler name for the error message.
attribute_name – The attribute key that must be present.
world_pos – The world-space position of the sample point.
samples – The attribute samples at that point (may be nullopt).

namespace StochasticSampler

Functions

MaterialSampleResult sample(const AttributeSamples &samples, double signed_distance, const std::shared_ptr<MaterialDefs> &material_defs, double liquid_keep_out_distance = 0.0, uint8_t liquid_material_id = 0)

Extracts VOLUME_FRACTIONS from samples and performs weighted stochastic material selection.

Applies liquid keep-out if configured.

Parameters:

samples – The attribute samples at the voxel location.
signed_distance – The signed distance value at the voxel location.
material_defs – Material definitions for color lookup.
liquid_keep_out_distance – Distance from surface within which liquid is removed.
liquid_material_id – The material ID of the liquid material.

Returns:

MaterialSampleResult with the selected material.

struct MaterialSampleResult

#include <stochastic_sampler.h>

Public Members

glm::vec4 color

bool is_active

uint8_t material_id

class VoxelGrid

#include <voxel_grid.h>

Public Functions

glm::vec3 bbox_max() const

glm::vec3 bbox_min() const

std::tuple<size_t, size_t, size_t> index_to_xyz(size_t index) const

glm::vec3 space_size() const

glm::vec3 voxel_size() const

VoxelGrid(glm::vec3 bbox_min, glm::vec3 bbox_max, glm::vec3 voxel_size)

glm::vec3 world_position(long x, long y, long z) const

long x_dim() const

size_t xyz_to_index(size_t x, size_t y, size_t z) const

long y_dim() const

long z_dim() const

Private Members

glm::vec3 m_max

glm::vec3 m_min

glm::vec3 m_space_size

glm::vec3 m_voxel_size

long m_x_dim

long m_y_dim

long m_z_dim