Voxelity Pro: Voxel File Format Exchange
1 Introduction
Voxelity 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.
Voxelity 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.
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 — Voxelity Pro brings unparalleled voxel conversion capabilities directly to Blender, enhancing your workflow and expanding your creative possibilities.
1.1 Overview
Voxelity 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.
1.2 Purpose
The primary goal of Voxelity 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
Voxelity 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.
Voxelity 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.
Disclaimer and Usage Guidelines: Please note that while Voxelity Pro is designed to handle a wide range of meshes, there are practical limits to its performance based on your computer's specifications. High voxel counts and large meshes require substantial computational resources, including CPU, GPU, and RAM. Attempting to process extremely high voxel counts on large meshes may result in Blender crashing or becoming unresponsive, which is a common limitation due to the intensive nature of voxel processing. Performance can vary greatly depending on your hardware setup, and it is recommended to start with moderate voxel counts and gradually increase them while monitoring your system's resource usage.
Refund Policy: Refunds will not be issued for issues arising from exceeding the practical limits of voxel counts and mesh sizes due to hardware limitations. It is understood that pushing the limits of any software or addon can lead to performance issues. By purchasing and using this addon, you acknowledge and accept these limitations and agree to use the addon within sensible guidelines based on your system's capabilities. Common sense dictates that extreme usage beyond hardware capabilities can lead to crashes, and such cases are not eligible for refunds.
1.4 Compatibility
Voxelity Pro is compatible with Blender versions 3.3 to 4.2 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 Help⇒Manual
However, if users choose to install it on lower versions, with the lowest version being 2.93, an older version with limited functionality will be available, though with reduced support.
1.4.1 Supported Voxel File Formats
Voxelity 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 | Voxelity Pro is fully compatible with Blender versions 3.3 through 4.2, and onwards. However, if users choose to install it on lower versions, with the lowest version being 2.93, an older version with limited functionality will be available, though 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 Voxelity 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.
Please note that on macOS, when you download the add-on ZIP file, the Safari web browser may automatically unzip it by default. The file must remain zipped, as Blender expects a ZIP file for installation. Re-zipping the file after it has been unzipped can sometimes cause issues. To prevent the file from automatically unzipping after purchase, make sure to disable this behavior by following these instructions in this thread.
2.3 Addon Installation
After downloading the Voxelity Pro addon and launching Blender on your system, you can install it by following these instructions:
- Go to menu Edit⇒Preferences...⇒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.
Please note that since Blender 4.2, addon installation process has slightly changed. Please see this thread for more information.
2.4 Addon Activation
To activate the Voxelity 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 Edit⇒Preferences...⇒Add-ons
Also please take note of the Blender version used. You can get the version by navigating to menu Help⇒Manual which opens a browser.
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're running Blender on a MacOS computer with an Apple Silicon processor, such as the M1, M1 Pro, M1 Max, M2, or later models, you’ll need to install Rosetta 2 for compatibility.
You can do this by enabling Developer Extras: Go to Edit⇒Preferences...⇒Interface and under Display section, check the option for Developer Extras. Then in the 3D Viewport, simply Press F3 then type "Install Rosetta 2" and run the command. If you're unsure whether your Mac requires Rosetta 2, you can try installing it anyway. If your device doesn't use Apple Silicon, the installation will simply fail, and you can safely ignore this outcome.
Once you're done, you’re ready 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
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.
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:
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 Edit⇒Preferences...⇒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.
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.
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 Voxelity 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 Voxelity Pro addon panel. You can then click the Voxelize button to convert your object to voxel mesh representation.
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 Voxelity File Conversion Panel
Voxelity 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.
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 File⇒Export⇒Voxelity 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.
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.
In the previous example we exported a .vox file which can be opened in MagicaVoxel
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 File⇒Import⇒Voxelity 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.
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.
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 Voxelity 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.
4 Troubleshooting
4.1 Common Issues
At this early stage, with Voxelity 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 |
|---|---|
| Overview Video | https://www.youtube.com/watch?v=t9KGAs-N9Z0 |
| 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 Voxelity 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.
Discover more products like this
qubicle Blender geometry nodes schematic magicavoxel voxel art minecraft 3D Exporting 3ds-importer voxel