Full Documentation: Settings

Source Texture

This is what you want to voxelize! Your mesh will be constructed based on this image, according to the settings detailed herein. This should be a texture asset in your project which has been imported with “Read/Write Enabled” enabled. If you have an image with transparency and want VOXORex to use that, you must also import with the “Alpha Is Transparency” option ticked.

If your Source Texture has a non-square aspect ratio, the voxels of the mesh will have exactly the same ratio, as will each tile. If that’s not what you want, you can get around it by using your image editor of choice and framing your image within a square transparent area.

Alpha Cutoff

Areas of the Source Texture where the transparency level (alpha) falls below this threshold will produce no voxels in your output. 

Output Tiles

Your output will consist of at least one tile. You can choose 1x1 (1 tile) up to 128x128 (16384 tiles) stepping up by powers of 2. Each tile is a mesh. Totally transparent tiles will not produce a mesh. In versions of Unity prior to 2017.3, tiles that would exceed the 64k vertex limit will not produce a mesh. Tiles have the same aspect ratio as the Source Texture. There are always the same number of tiles wide and deep. A larger number of tiles will increase the amount of voxels used to construct the output, thus accessing and visualizing greater detail in your Source Texture. All tiles will be correctly arranged within a parent Game Object, so you have a handy reference for their relative positions. VOXORex is usually done in times of less than a second to a few seconds, but note that more tiles and larger tile sizes do add to the time it takes, and use more system memory after finishing, while rendering the meshes (but you won’t be noticing these things unless you go really big). 

Tile Size

Your tiles could hypothetically each have up to this many voxels in width and depth, per Vertical Tier, were they completely solid. In practice, successively higher Vertical Tiers will have drastically less voxels than those below, depending on your Source Texture and settings. Each voxel stack's height is algorithmically determined by the Height Based On setting and related settings in the Voxel Settings group. Available options are powers of 2 from 1 to 1024. The larger your tile size, the number of voxels, and thus mesh vertices, increases exponentially. A mesh with more vertices takes more storage and memory, and for meshes with vertex colour attribute, an additional 4 floating point numbers are stored for every vertex. A mesh with a million vertices and colours, which you can certainly exceed by far in VOXORex, is not a small file. So if you are going for game-usable assets that won’t break your poly count and bloat your file size, keep it in mind. If you are going for mind-blowing bespoke art, crank it up if your system can take it. I’ve set the limits quite high. Note that VOXORex logs to the console the number of vertices and triangles per mesh it creates, for your reference.

Height Based On

This is how each voxel stack's height is determined from the Source Texture. You may choose from Hue, Lightness, Saturation, Alpha, Red, Green, or Blue. Each part of your Source Texture corresponding to each voxel stack will have that attribute of its colour analysed out of the range [0, 1] (except: see Normalize Height Input and Clamp Height Input) to determine voxel stack height for any given X, Z. In most cases the value is determined by a bilinear pixel lookup. For your chosen Vertical Tiers value, a voxel stack will reach that many voxels high if its height basis value is equal to maximum. If you choose 24 Vertical Tiers and Height Based On Lightness, a voxel stack will be 24 voxels high if it corresponds to a point in the Source Texture that is at maximum Lightness. A voxel stack would be 1 voxel high if it corresponds to minimum Lightness. Voxel stacks are at least 1 high unless the Source Texture or Shape Texture is under its Alpha Cutoff at that corresponding point.

Invert Height Input

See Height Based On. This will switch low areas for high, i.e. a voxel stack corresponding to maximum height basis would be 1 high.

Normalize Height Input

See Height Based On. This will set the compared minimum and maximum height basis values to the least and most found in the Source Texture, rather than [0, 1]. This should magnify the differences in height present.

Mutually exclusive with Clamp Height Input.

Clamp Height Input / Histogram

See Height Based On. This will set the compared minimum and maximum height basis values to the specified values using the range slider provided, rather than [0, 1]. This disregards any areas of the Source Texture where the height basis value is outside the range, turning them into cutouts. This restricted range will still be mapped proportionally to the full available height specified by Vertical Tiers. 

You can use the histogram displayed below the slider to analyse the image data and decide where you want the range. Height input values are sorted into bins that are 10% wide. You can click the histogram for a larger windowed view where you can also see how many pixels per bin there are. You cannot change the histogram - rather, it will be immediately reverted to correct data.

Mutually exclusive with Normalize Height Input.

Vertical Tiers

This is how many voxels high the areas corresponding to the maximum height basis values in the Source Texture will be. Other voxel stacks are equally proportional to their height basis. More Vertical Tiers will increase the number of mesh vertices.

Shape Stencil

This tells VOXORex how to determine the shape of your output, i.e., which voxel stacks are allowed to have some voxels, based on their location in the XZ plane and the relevant Alpha Cutoff (there could be up to 2 Alpha Cutoffs being applied depending on your settings). Set to Source Texture, the Source Texture’s transparency alone will determine the shape. Set to Shape Texture, you can select another texture that will also control the shape in combination with the Source Texture.

Shape Texture

This image will be applied as a stencil, i.e., transparent areas defined by this image will not appear in the output. This should be a texture asset in your project which has been imported with “Read/Write Enabled” enabled. If you have an image with transparency and want VOXORex to use that, you must also import with the “Alpha Is Transparency” option ticked. If you do not use transparency in the Shape Texture, you will get a square / rectangular tile.

Invert Shape Cutout

When inverted, non-transparent areas defined by the Shape Texture will not appear in the output.

Shape Alpha Cutoff

Areas of the Shape Texture where the transparency level (alpha) falls below this threshold will produce no voxels in your output. 

Vertex Colour Based On

You can apply vertex colour to your output meshes according to several strategies:             

• Height: Apply a colour to each vertex according to its relative Y position out the the number of Vertical Tiers. 

• Width: Apply a colour to each vertex according to its relative X position out of the total width of the output.

• Depth: Apply a colour to each vertex according to its relative Z position out of the total depth of the output.

• Source Texture Per Face: Each voxel stack will be a single, solid colour, according to its corresponding position in the Source Texture. This results in a quite accurate yet more pixelated / cube-constructed look. Will not have any blurring when viewed close-up.

• Source Texture Per Vertex: Each vertex stack will be a single, solid colour, according to its corresponding position in the Source Texture. This results in an even more accurate and precisely painted look since colours can blend across faces. Could look blurry when viewed close-up, especially for smaller meshes.

• Albedo Texture Per Face:  Each voxel stack will be a single, solid colour, according to its corresponding position in a specified Albedo Texture. This results in a quite accurate yet more pixelated / cube-constructed look. Will not have any blurring when viewed close-up.

• Albedo Texture Per Vertex: Each vertex stack will be a single, solid colour, according to its corresponding position in a specified Albedo Texture. This results in an even more accurate and precisely painted look since colours can blend across faces. Could look blurry when viewed close-up, especially for smaller meshes.

Gradient Source

If Vertex Colour Based On is set to Height, Width, or Depth, this option is visible. You can choose Key to set up a gradient colour key in the Inspector, or Texture to read the colours from a specified texture. Gradient colours are applied from the start of the gradient at the least Height / Width / Depth, to the end of the gradient at the most Height / Width / Depth, with some options to change that.

Gradient Texture

If Gradient Source is set to Texture, this option is visible. Choose a texture in your project and the first column of pixels will be applied as a colour gradient, with the lowest Y pixel being the start of the gradient. This should be a texture asset in your project which has been imported with “Read/Write Enabled” enabled. 

Height / Width / Depth Based Colours

If Gradient Source is set to Key, this option is visible. You can set up a standard gradient colour key. Alpha values will be ignored. These gradients are limited (by Unity) to 8 keys.

Gradient Multiplier

If Vertex Colour Based On is set to Height, Width, or Depth, this option is visible. Your gradient colours are by default applied once across the entire output, but you can increase it with the provided slider. See Gradient Repeat Mode.

Invert Gradient

If Vertex Colour Based On is set to Height, Width, or Depth, this option is visible. Your gradient colours are by default applied from the start of the gradient at the least Height / Width / Depth, to the end of the gradient at the most Height / Width / Depth. When inverted, they are applied from the end of the gradient at the least Height / Width / Depth, to the start of the gradient at the most Height / Width / Depth.

Gradient Repeat Mode

If Vertex Colour Based On is set to Height, Width, or Depth, this option is visible. You can choose how the gradient will repeat when the Gradient Multiplier is greater than 1. Symmetric means that after it reaches the end colour, it will start from the end colour and go back toward the start colour, producing a smooth blend where the gradient ends and starts. Asymmetric means the colours will cycle back to start after every end, potentially producing a disjointed colouring effect.

Albedo Texture

If Vertex Colour Based On is set to Albedo Texture Per Face or Albedo Texture Per Vertex, this option is visible. Choose a texture in your project and the colours will be applied according to the description under Vertex Colour Based On. This should be a texture asset in your project which has been imported with “Read/Write Enabled” enabled. 

Albedo Transparency To

If Vertex Colour Based On is set to Albedo Texture Per Face or Albedo Texture Per Vertex, this option is visible. Areas of the output that correspond to transparent areas in the Albedo Texture will be this colour.

Colour by Face Dir

Sets the colour of vertices according to which direction the mesh face they are on is pointing. In a VOXORex- constructed mesh, faces do not share corner vertices. Therefore, a top face and side face of the same voxel can be entirely different colours with no bleed between them. This colour takes priority over all other colour settings except Shadow.

Assign North / South / East / West / Top / Bottom

All faces in the chosen direction(s) will have a specified colour. VOXORex refers to the mesh faces as follows: 

• North = facing +Z when constructed.

• South = facing -Z when constructed.

• East = facing +X when constructed.

• West = facing -X when constructed.

• Top = facing +Y when constructed.

• Bottom = facing -Y when constructed. This option is only visible when Bottom Mesh Type is not set to None.

Shadow Direction

This allows you to simulate a shadow or colour tint coming from a cardinal direction and affecting your output. See above for explanation of face directions.

Shadow Colour

If Shadow Direction is not set to None, this colour will be blended into your output’s colours after other settings have been applied, with full strength at the outer limit of the output and decreasing to none at the chosen width or depth.

Shadow Width / Depth

If Shadow Direction is not set to None, this proportion of your output by Width or Depth will be affected by the Shadow Colour.

Bottom Mesh Type

You can use the Bottom Mesh Type options to add a Flat mesh, a Vertical Mirror mesh, or None at all. Any bottom topology is combined into a tile’s mesh, not put on a second mesh. This is how it should be, but do note that by using these options you will be increasing the amount of vertices required for your design by up to 2x.

• Flat bottom meshes will present a smooth solid plane of faces on the bottom of the mesh, which have the same colour as the faces above.

• Vertical Mirror will mirror the mesh topology across the XZ plane, resulting in a mirrored (not simply flipped) version of the mesh extruding from 0 Y into -Y. By using Vertical Mirror, you can create some truly impressive 3D meshes and game-usable assets.

Mesh World Size Y

This is the final height in the Y axis to which your output will be set at scale = 1. If Vertical Mirror is used, this applies in both directions, therefore the size is doubled. This doesn’t affect the number of vertices or mesh topology, it is simply a default scale.  

Center Mesh Pivots

By default, mesh pivots will be in the -X, -Y, -Z corner. You can tick the Center Mesh Pivots option to have each tile, no matter its shape, have its mesh’s pivot centered within the bounds of the mesh.

Add Mesh Collider

By default, output meshes will not have a Collider. You can tick the Add Mesh Collider option to give each mesh a MeshCollider. This can be useful for in-game runtime generation.

Mesh Material

You can select a Material that will be applied to all the Mesh Renderer components in your output. If you leave this blank, VOXORex will assign an appropriate material, depending on your project’s active Rendering Pipeline, from those included. You can assign your own materials that support vertex colour, and they will work. Each individual voxel face is also UV mapped to display textures, if the material uses any.

Mesh Name

Your output will consist of one or more meshes. Each mesh’s name can be specified by you and automatically appended with a tile number by VOXORex. You can leave the Mesh Name blank to have VOXORex assign a unique hashcode name based on the time the script was enabled in Play mode.

Log To Console

By default, information about each mesh produced will be written to the Console. You can untick the Log To Console option to suppress this behaviour. This can be useful for in-game runtime generation.

Select In Hierarchy

By default, the parent GameObject of the output meshes will be automatically selected in the Unity Editor Hierarchy window. You can untick the Select In Hierarchy option to suppress this behaviour. This can be useful for in-game runtime generation.

Position Camera On Finished

By default, VOXORex will attempt to position the main camera, if any, so that the output can be seen in entirety. You can untick the Position Camera On Finished option to suppress this behaviour. This can be useful for in-game runtime generation.

Wall Cube

This special feature of VOXORex allows you to produce infinite variations of game-ready, overall cube shaped walls with differently coloured and detailed voxel surfaces - think rock walls, brick walls, ice walls, spaceship corridor walls, modern interior walls, any type of surface you want to present as a wall! And all it takes is a minute of selecting your image(s) and tuning your settings.

If you tick Wall Cube, your output will be limited to 1 tile (of any size). That’s because that entire tile will be quadruplicated and used as the four side faces of a 4x4x4 world unit sized cube. You can use bottom meshes, subject to common sense - if the interior will never be seen, don’t waste the vertex count! On the other hand, you can make a tunnel section, hallway or entrance way using a bottom mesh with Wall Cube (see provided Example Presets).

The Wall Cube will be combined into a single mesh, with potentially another quad, so if you are running VOXORex in a version of Unity prior to 2017.3, be aware that your tile should have no more than 16380-16384 vertices to get a successful result. For game assets where performance matters, you should probably stick to no more than 4 Vertical Tiers, and Tile Size 64 (those are at most!), to keep the resulting combined mesh around 12k - 20k vertices. If your game is rendering only visible surfaces, that’s quite reasonable per wall side (3k - 5k; about the same as a nice tree model; and you can go even lower on the settings).

Wall Top Quad

If Wall Cube is ticked, this option is visible. Your Wall Cube can have a solid top face by enabling Wall Top Quad. It has a separate material slot from the rest of the wall. No colour will be set on the Wall Top Quad’s vertices unless you set Shadow Direction to North, in which case it will have the shadow colour at full strength. 

Wall Top Material

You can assign a material here to have it automatically displayed on your output’s Wall Top Quad. If you leave this blank, VOXORex will assign an appropriate material, depending on your project’s active Rendering Pipeline, from those included. You can assign your own materials that support vertex colour, and they will work. The Wall Top Quad’s face is also UV mapped to display textures, if the material uses any.

Runtime Generation / Use VOXORex in Your Game

VOXORex can be included in your scenes and activated at the right time (controlled by you) to create your game world models from textures.

• Suppress reporting and convenience options: turn off Log To Console, Select In Hierarchy, and Position Camera On Finished.

• If you want a Mesh Collider on the output, turn on the Add Mesh Collider option.

• Have the VOXORex script disabled in your scene or prefab.

• Add to your script: using ABCodeworld.VOXORex;

• Assuming you have a reference to your VOXORex component as MyVox, add a listener to the GenerationComplete event: MyVox.GenerationComplete += MyHandlerMethod;

• Your listener should have a single parameter of type GameObject. This is the parent of all meshes that MyVox will output when enabled.

• After this you can enable the component (MyVox.enabled = true;)

Saving and Using Your Output

I suggest you make prefabs out of the settings you like, so you can re-generate or modify them at any time.

VOXORex does not automatically save meshes for you, but you can do that if you are satisfied with your output! VOXORex includes one way to accomplish that - the freely available MeshSaverEditor.cs script. It allows you to right-click any Mesh Filter component on a Game Object in the Hierarchy and save the mesh as a Unity mesh .asset file. Also, Unity provides at least two more ways to save meshes from the Hierarchy. The glTFast package (Git URL: com.unity.cloud.gltfast) allows you to right-click any Mesh Filter component on a Game Object in the Hierarchy and save the mesh as a binary .glb or text .glt file. The FBX Exporter package, available in Package Manager (and via Git URL: com.unity.formats.fbx), does the same for .fbx files. Both of these formats can be imported into most other content creation software, such as Blender (Blender tip: to see the vertex colours, you have to assign a Colour Attribute to the object’s material’s Albedo, and be in Material Preview or Rendered mode). PS - make sure you export the vertex colour!

Regarding preserving the relative positioning of multiple output tiles, all you need to do is drag the parent object of the tiles, in Play mode, to the Project window to create a prefab. The prefab will have everything saved except the meshes assigned in the Mesh Filters, because the meshes existed only in memory when the prefab was created, not as a referenceable object. You can restore the Mesh Filters’ assigned meshes at any time once the meshes are saved by dragging them from the Project window.

Tips

• You can use different-sized and proportioned images for Source Texture, Shape Texture, and Albedo Texture. They will be mapped to the same space before operations are applied. The Gradient Texture is a special case, please see that section in Settings Descriptions.

• VOXORex does not combine adjacent, coplanar, same material mesh faces by design, so that each voxel can have a separately assigned colour. You can combine them with other mesh tools, but the vertex colours will be affected.