Voxility Pro: Voxel File Format Exchange

by Harry McKenzie in Addons


1 Introduction

Voxility Pro: Voxel File Format Exchange is a comprehensive Blender addon designed to revolutionize your voxel-based workflows. With its intuitive features and seamless integration, it empowers artists and designers to unleash their creativity and explore new dimensions of voxel modeling within the familiar Blender environment.

Voxility Pro supports seamless import and export of various popular textured voxel file formats, including MagicaVoxel.vox Qubicle.qb Voxlap.vxl and a plethora of many more voxel file formats, ensuring compatibility with a wide range of voxel editors and game engines. Additionally, this addon introduces an integrated voxelization feature for textured meshes, allowing for streamlined voxelization directly within Blender.

Voxility Docoration

Powered by vengi-voxconvert, a cutting-edge voxel conversion tool developed by Martin Gerhardy as part of Vengi Voxel — an open-source and multi-platform voxel editor — Voxility Pro brings unparalleled voxel conversion capabilities directly to Blender, enhancing your workflow and expanding your creative possibilities.

1.1 Overview

Voxility Pro offers a robust set of tools and functionalities tailored specifically for voxel modeling enthusiasts. From integrated Mesh Voxelization to Import and Export capabilities, this addon provides a complete solution for incorporating voxel-based techniques into your projects.

Voxility Pro N-Panel Voxelize Button
Voxility Pro functions available in N-Panel and Import and Export submenus.
1.2 Purpose

The primary goal of Voxility Pro is to simplify the process of working with voxel data in Blender while preserving the fidelity of your original models. One of its standout features is the ability to convert meshes with textures into voxel-type meshes. These voxel meshes can be exported to various formats such as MagicaVoxel.vox Qubicle.qb Voxlap.vxl and many more voxel file formats. Importantly, this addon preserves color information during the conversion process, enabling seamless transitions between traditional mesh modeling and voxel-based workflows.

1.3 Functionality

Voxility Pro boasts a range of powerful functionalities.

1.3.1 Functionalities
Feature Description
Mesh Voxelization Transform polygonal meshes into voxel-based representations with ease.
Texture Preservation Retain color information from textures during mesh-to-voxel conversion.
Bake Texture Bake any voxelized object with complex shaders into one Diffuse texture for easy export.
Import / Export Seamlessly import and export voxel file formats for compatibility with various voxel editors and game engines.
Efficient Workflow Intuitive tools and customizable settings streamline your voxel modeling workflow, enabling you to focus on your creative vision.
1.3.2 Limitations

Most file formats don't support exporting complex textures, let alone full-blown material definitions or other application-specific features. For more detailed information on this limitation, please refer to this link. Hence, we only support simple material definitions, either through the Image Texture node or basic color Diffuse definitions via the Principled BSDF node's Base Color socket.

No need to worry. Our integrated Bake Feature still enables you to use complex shaders to create model Diffuse colors. Just click Bake to consolidate shaders into a single Image Texture for easy export. Keep in mind, this process flattens your object by applying all modifiers, including the voxelization modifier, so ensure you back up your object beforehand. Baked images are not automatically saved, so remember to save them manually before closing to avoid losing them.

Currently, the addon is restricted to utilizing only one UV Map and/or Color Attribute per object. However, you still have the flexibility to employ multiple UV maps and Color Attributes and subsequently bake the outcome in order to successfully export the result.

Voxility Pro works best with manifold meshes. For optimal voxelization results, ensure that objects possess a volume or thickness equal to or greater than the voxel size. For instance, a flat mesh lacking thickness will vanish during voxelization. To resolve this, simply extrude it to provide the necessary thickness or consider using a Solidify modifier.

1.4 Compatibility

Voxility Pro is compatible with Blender versions 3.3 to 4.1 and above, running on Microsoft Windows, Mac OS, or Linux Platforms, ensuring broad accessibility for Blender users. You can easily identify the version of Blender you're using by accessing menu HelpManual

Check Blender Version
In this example, we're using Blender version 4.0

However, if users choose to install it on lower versions up to 2.93, an older version with limited functionality will be available, although with reduced support.

1.4.1 Supported Voxel File Formats

Voxility Pro supports a wide range of formats, and we are continually adding more support. Currently, the following types are supported, indicated by a checkmark for their corresponding import or export format.

Voxel File Format Name File Extension Import Export
MagicaVoxel .vox
Qubicle Binary Exchange .qb
Qubicle Binary Tree Exchange .qbt
Qubicle Exchange Format ASCII .qef
Qubicle Project .qbcl
Binvox command line voxelizer .binvox
CubeWorld CubeMap .cub
Minecraft Schematic .schematic
Minecraft level dat .dat
Minecraft Anvil Region .mca
Minetest Template .mts
Sandbox VoxEdit Collection .vxc
Sandbox VoxEdit Hierarchy .vxr
Sandbox VoxEdit Tilemap .vxt
Sandbox VoxEdit Model .vxm
MagicaVoxel XRAW .xraw
Tiberian Sun .vxl
Voxlap Voxel Engine .kv6
Voxlap Voxel model format .kvx
Animatoon 3D Scene .scn
Sproxel csv .csv
StarMade Blueprint .sment
Goxel .gox
Voxel Max .vmax
Voxel Builder .vbx
Voxel3D .v3a
Vengi .vengi
Nicks Voxel Model .nvm
Particubes .pcubes
CuBic Mesh .csm
Cubzh .3zh
Cubzh World .b64

2 Installation

We will guide you through each step of the installation process in a systematic manner.

2.1 Addon Requirements

It is crucial to ensure that your system meets all the necessary requirements for running this addon effectively. Please verify the following requirements:

Requirement Description
Blender Version Voxility Pro is fully compatible with Blender versions 3.3 through 4.1, and onwards. However, if users choose to install it on lower versions up to 2.93, an older version with limited functionality will be available, although with reduced support.
Operating System Supported on Windows, Mac OS, and Linux platforms.
Hardware Requirements Your system should meet the minimum hardware specifications recommended for running Blender smoothly.
2.2 Addon Download
  • Locate the Voxility Pro addon product page.
  • Click on the Purchase or Download button to obtain the addon.
  • Complete the payment process if required.
  • Once the download is complete, you will receive a .zip file containing the addon.
2.3 Addon Installation

After downloading the Voxility Pro addon and launching Blender on your system, you can install it by following these instructions:

  • Go to menu EditPreferences...Add-ons
  • At the top right of the window, click on the Install... button.
  • Navigate to where you downloaded the .zip file and select it.
  • Click the Install Add-on button to install the addon.
  • Enable the addon by checking the checkbox as shown below.
Voxility Pro Installation
The Voxility Pro addon is now successfully installed in Blender
2.4 Addon Activation

To activate the Voxility Pro addon and unlock its full range of features, please follow the instructions provided below based on your respective Operating System, and review the following information. Take note of the voxconvert version, which is an executable binary file used within this addon, because this information may be needed after addon installation depending on your Operating System. Open EditPreferences...Add-ons

Check Addon Version and Voxconvert version
In this example, Voxility Pro version is 1.0.12 and the voxconvert version is 0.0.29

Also please take note of the Blender version used. You can get the version by navigating to menu HelpManual which opens a browser.

Check Blender Version
In this example the Blender version is 4.0
2.4.1 Microsoft Windows Activation

If you are running Blender on Microsoft Windows then you are all set. Please feel free to proceed to the Getting Started section.

2.4.2 Apple Mac OS Activation

If you are running Blender on a Mac computer then you are all set. Please feel free to proceed to the Getting Started section.

2.4.3 Linux Platform Activation

After installing the addon on Blender running on Linux, open the Linux Console or Terminal and copy-paste the following command text into any text editor. Then modify the text to adjust to your Blender version (e.g.4.0) and the voxconvert version (e.g.0.0.29). Then copy-paste the new modified text into your Linux Console and press Enter

Linux Console
cd ~/.config/blender/4.0/scripts/addons/voxility_pro/voxconvert-executable/0.0.29/linux/

Make sure the path is correct and there are no errors. Then copy the following commands line by line and paste each line into terminal and press Enter. Read the terminal outputs, because you may need to type in y for yes and press Enter to confirm command.

Linux Console
sudo dpkg -i vengi-shared_0.0.29.0-1_amd64.deb
sudo dpkg -i vengi-voxconvert_0.0.29.0-1_amd64.deb
sudo apt-get install -f

Read the output for each line you execute and make sure there are no errors. Finally test if you have successfully installed vengi-voxconvert by typing in the following command:

Linux Console
vengi-voxconvert --version

This should print out the voxconvert version. If successful, close Blender, reopen it, and the command should become available for Blender.

3 Getting Started

We'll walk you through the initial steps to familiarize yourself with our addon and its basic functionalities. Whether you're a newcomer or a seasoned user, this guide will help you navigate through the essential features and get you up to speed quickly.

3.1 Configuration Options

Enhance the addon by navigating to menu EditPreferences...Add-ons and searching for VOXILITY. Then, click the small arrow located to the left of the addon name and checkbox. This action will unveil a plethora of configuration options, allowing you to personalize your experience and tailor the application to meet your unique requirements.

Voxility Pro Configuration Options
By default every voxel format is checked. Uncheck irrelevant items.

Select the checkboxes corresponding to the voxel file formats you'll use. This streamlines the voxel formats list by hiding irrelevant choices during object import/export, preventing clutter and ensuring a smoother workflow. Observe that the import list and export list (supported export formats only) now exclusively presents the options you've configured.

Voxility Pro Configuration Customization
Here we have only a few options checked which hides irrelevant formats.

NOTE: Don't forget to save your preferences using Save Preferences button located in the lower left corner of the Preferences window, so you don't have to tick the checkboxes again the next time you open Blender.

3.2 User Interface Overview

In this section, we'll provide an overview of the user interface to familiarize you with the main components and features.

3.2.1 Voxility Pro Panel

You can convert your textured mesh objects into voxel representation directly within Blender. Simply position your mouse in the 3D Viewport and press the N key. This will prompt the Sidebar, commonly known as the N-Panel to appear. From there, you can easily locate and click on the Voxility tab button to open the Voxility Pro addon panel. You can then click the Voxelize button to convert your object to voxel mesh representation.

Voxility Pro N-Panel Voxelize/Unvoxelize Button
Select the mesh object or objects and click the Voxelize/Unvoxelize button.

If your intention is to export the resulting voxel mesh, you have the option to choose a Target export voxel format from the dropdown menu situated within the expandable Export tab. Hover your cursor over each option to unveil a tooltip providing an explanation for each property, allowing for a comprehensive understanding of their respective functionalities.

WARNING: Before delving into larger projects, it's recommended to start with smaller objects containing fewer vertices to familiarize yourself with the addon's functionality. Processing time can vary significantly, ranging from seconds to several minutes, depending on the complexity of your object and your computer specifications. Objects with large dimensions, as well as higher vertex and face counts, tend to be more complex. Therefore, consider reducing the number of vertices through decimation before using certain features. While the interface may appear unresponsive, rest assured it is processing. Please be patient while the process completes.

Below are the distinct functionalities provided by the addon panel:

Function Description
Voxelize Button Adds a voxelization Geometry Nodes modifier to the selected objects. Avoid directly modifying the modifier, as the addon automatically handles any necessary adjustments.
Voxel Size Change the size or dimension of the voxels usually in meters between 0.01 to 100. If you need more detail, scale the entire model and Apply scale.
UV Map Active Object's UV Map if any. Only one UV map is supported per object. See Limitations section
Vertex Colors Active Object's Color Attribute if any. Only one Color Attribute is supported per object. See Limitations section
Export Target Specify the desired voxel file format for export.
Check Problems Click to validate your voxel mesh prior to export.
Bake Button Optionally bake your object and colors or shaders into a single Image Texture for exporting complex shaders not directly supported. Baking will flatten your object or apply all modifiers, so be sure to back up your object beforehand. Baked images aren't automatically saved, so remember to save them manually before closing to avoid losing them.
Export Button Click to export your voxel mesh to the specified Export Target
3.2.2 Voxility File Conversion Panel

Voxility File Conversion panel can be accessed by clicking anywhere within the 3D Viewport, ensuring that no object is selected. Browse for an Input File, choose a Target format, and then click the Convert button to select a location for saving the result.

Voxility Pro N-Panel File Conversion Panel
Select a file of any supported voxel file format and convert to a Target format

3.2.3 Export Voxel Format File

You have the flexibility to export your models to a diverse range of widely recognized and popular voxel file formats, including MagicaVoxel.vox Qubicle.qb Voxlap.vxl and many more voxel file formats by accessing the export options through menu FileExportVoxility Voxel Formats.* and selecting a voxel format of your choice. You can streamline this export list by filtering out only the relevant options through the Configuration Options.

Voxility Pro Export Voxel Format File
Export to any supported voxel file format of your choice

Simply select all mesh objects and click Voxelize button and then export. You will be presented with the Export Dialog where you can select a location and input a file name. Press the Export button to start the conversion process and save it to your chosen destination. This may take some time, so please be patient.

Voxility Pro Export Voxel Format Dialog
In this Export Dialog example we are exporting to .vox file format

In the previous example we exported a .vox file which can be opened in MagicaVoxel

MagicaVoxel Preview
This is a sample render preview in MagicaVoxel of the exported .vox file.

MagicaVoxel is just one example of various software and game engines that are capable of processing a wide array of voxel file formats, each designed to accommodate different needs and functionalities.

WARNING: Before delving into larger projects, it's recommended to start with smaller objects containing fewer vertices to familiarize yourself with the addon's functionality. Processing time can vary significantly, ranging from seconds to several minutes, depending on the complexity of your object and your computer specifications. Objects with large dimensions, as well as higher vertex and face counts, tend to be more complex. Therefore, consider reducing the number of vertices through decimation before using certain features. While the interface may appear unresponsive, rest assured it is processing. Please be patient while the process completes.

3.2.4 Import Voxel Format File

You have the flexibility to import your models from a diverse range of widely recognized and popular voxel file formats, including MagicaVoxel.vox Qubicle.qb Voxlap.vxl as well as numerous other voxel file formats by accessing the import options through menu FileImportVoxility Voxel Formats.* and selecting a supported voxel file. You can streamline this import list by filtering out only the relevant options through the Configuration Options.

Voxility Pro Import Voxel Format File
Import any supported voxel file format of your choice

Once you have chosen a voxel format, you will be presented with the Import Dialog where you can select a file to import. You can also adjust the import options. Hover your cursor over each option to unveil a tooltip providing an explanation for each property, allowing for a comprehensive understanding of their respective functionalities. Press the Import button to start the import process. This may take some time, so please be patient.

Voxility Pro Import Voxel Format File
In this Import Dialog example we are importing a .vox file

WARNING: Before embarking on larger projects, it's recommended to start with smaller files to familiarize yourself with the addon's features. Processing times can vary significantly, ranging from seconds to several minutes, depending on the complexity of your voxel file and your computer specifications. While the user interface may seem unresponsive or stalled, rest assured it is diligently processing. Please be patient while the process completes.

3.3 Voxility Logging

It is recommended to switch to the Scripting workspace tab so you can see the processing output, and please take note of the dimension of the object. The larger the object in dimensions, the more voxel detail you can produce, but it may take longer to process. The output will be visible in the Info Editor.

Scripting Tab Logging and Debugging
Logs are in the Info Editor within Scripting Tab

4 Troubleshooting

4.1 Common Issues

At this early stage, with Voxility Pro being newly released, we're pleased to inform you that there haven't been any common issues reported thus far. However, for any questions or concerns, please feel free to reach out to us via Blender Market, the platform through which you acquired the addon, and we'll be more than happy to assist you promptly.

5 Support and Community

5.1 Contact Information

Please reach out to us via Blender Market, the platform through which you acquired the addon. We are committed to promptly addressing any concerns or issues you may encounter. We're excited to announce that we will soon be launching a Discord community. Stay tuned for updates, as we look forward to connecting with you and fostering a vibrant community of Blender enthusiasts.

6 Appendix

6.1 Glossary
Term Description
Voxel Volumetric pixel used in 3D modeling and computer graphics to represent volumetric data.
Voxelization Process of converting a mesh or other 3D data into a voxel representation.
Addon Piece of software that extends the functionality of Blender, designed to enhance and streamline various aspects of the Blender workflow.
Texture Surface appearance of an object when it's rendered. It includes characteristics such as color, roughness, reflectivity, and bumpiness, etc.
VOX File Simple binary format used to store voxel data. It consists of a header section followed by the voxel data, which is typically encoded using run-length encoding (RLE) or other compression techniques to reduce file size.
MagicaVoxel Voxel modeling software that uses its own proprietary file format (.VOX) for saving voxel models.
Qubicle Voxel modeling software that uses its own file format (.QB) for saving voxel models.
Executable External program or script that can be run by Blender as a separate process.
Terminal or Console Provides a command-line interface where users can type commands directly to interact with the operating system and run various programs or utilities.
ZIP File Compressed archive that contains script and one or more assets. Users can install these addons by importing the zip file directly into Blender's addon manager, simplifying the installation process.
6.2 Additional Resources

Resource Resource Link
Voxconvert Documentation https://vengi-voxel.github.io/vengi/voxconvert/Index/
Voxconvert Tutorial https://www.youtube.com/watch?v=Erstqc5uSxU
6.3 Version History

Previously known as MagicaVoxel Vox Exporter, this addon initially offered only basic export functionality for MagicaVoxel only. Renamed as Voxility Pro we have significantly expanded its capabilities to include both import and export functions for various formats. Additionally, we've introduced a dedicated panel within Blender that facilitates in-app voxelization — a feature designed to enhance your voxel modeling experience.

Sales 10+
Dev Fund Contributor
Published 2 months ago
Blender Version 4.1, 4.0, 3.6, 3.5, 3.4, 3.3
License GPL
Have questions before purchasing?

Contact the Creator with your questions right now.

Login to Message