MagicaX.VoxGenerator (MagicaX v0.1.0)

A flexible VOX file generator for MagicaVoxel format.

Supports multiple input methods:

Direct programmatic generation
JSON-to-VOX conversion with comprehensive validation
Built-in shape generators (cube, sphere, teapot)
Custom palette support with 256-color capability

Examples

# Generate from JSON file
{:ok, message} = MagicaX.VoxGenerator.generate_from_json_file("model.json")

# Generate programmatically
dimensions = {10, 10, 10}
voxels = [{0, 0, 0, 1}, {1, 1, 1, 2}]
{:ok, message} = MagicaX.VoxGenerator.generate_vox_file("model.vox", dimensions, voxels)

# Generate basic shapes
{:ok, message} = MagicaX.VoxGenerator.generate_cube("cube.vox", 10)
{:ok, message} = MagicaX.VoxGenerator.generate_sphere("sphere.vox", 8)

Summary

Functions

generate_cube(filename, size \\ 10)

Creates a simple cube VOX file.

generate_from_json(filename, json_string)

Generates a VOX file from JSON data.

generate_from_json_file(json_filename, output_filename \\ nil)

Generates a VOX file from a JSON file with automatic output naming.

generate_from_map(filename, data)

Generates a VOX file from a parsed JSON map.

generate_sphere(filename, radius \\ 10)

Creates a sphere VOX file.

generate_teapot(filename, scale \\ 1.0)

Creates a teapot-like shape VOX file.

generate_vox_file(filename, dimensions, voxels, palette \\ nil)

Generates a new VOX file with specified dimensions and voxel data.

Functions

generate_cube(filename, size \\ 10)

Creates a simple cube VOX file.

Parameters

filename - Output VOX file path
size - Cube size (default: 10)

Returns

{:ok, message} - Success message
{:error, reason} - Error description

generate_from_json(filename, json_string)

Generates a VOX file from JSON data.

JSON Structure

{
  "dimensions": [x, y, z],           // REQUIRED: 3D dimensions
  "voxels": [                        // REQUIRED: Array of voxel objects
    {
      "x": 0,                        // REQUIRED: X coordinate (0-255)
      "y": 0,                        // REQUIRED: Y coordinate (0-255)
      "z": 0,                        // REQUIRED: Z coordinate (0-255)
      "color_index": 1               // REQUIRED: Color index (0-255)
    }
  ],
  "palette": [                       // OPTIONAL: Custom color palette
    {
      "r": 255,                      // REQUIRED: Red component (0-255)
      "g": 255,                      // REQUIRED: Green component (0-255)
      "b": 255,                      // REQUIRED: Blue component (0-255)
      "a": 255                       // REQUIRED: Alpha component (0-255)
    }
  ],
  "metadata": {                      // OPTIONAL: File metadata
    "name": "My VOX Model",
    "author": "Creator Name",
    "description": "Model description"
  }
}

Example

json = """
{
  "dimensions": [10, 10, 10],
  "voxels": [
    {"x": 0, "y": 0, "z": 0, "color_index": 1},
    {"x": 1, "y": 0, "z": 0, "color_index": 2}
  ]
}
"""
MagicaX.VoxGenerator.generate_from_json("output.vox", json)

generate_from_json_file(json_filename, output_filename \\ nil)

Generates a VOX file from a JSON file with automatic output naming.

If no output filename is provided, it will use the same name as the JSON file but with .vox extension.

Examples

# Creates model.vox from model.json
MagicaX.VoxGenerator.generate_from_json_file("model.json")

# Creates custom.vox from model.json
MagicaX.VoxGenerator.generate_from_json_file("model.json", "custom.vox")

generate_from_map(filename, data)

Generates a VOX file from a parsed JSON map.

generate_sphere(filename, radius \\ 10)

Creates a sphere VOX file.

Parameters

filename - Output VOX file path
radius - Sphere radius (default: 10)

generate_teapot(filename, scale \\ 1.0)

Creates a teapot-like shape VOX file.

Parameters

filename - Output VOX file path
scale - Scale factor (default: 1.0)

generate_vox_file(filename, dimensions, voxels, palette \\ nil)

Generates a new VOX file with specified dimensions and voxel data.

Parameters

filename - Output VOX file path
dimensions - Tuple of {x, y, z} dimensions
voxels - List of {x, y, z, color_index} tuples
palette - Optional custom palette (defaults to built-in palette)

Returns

{:ok, message} - Success message
{:error, reason} - Error description