voxelizer/Readme.md

8.4 KiB

Logo

Voxelizer (voxelizer)

Turns 3D models into astonishing voxel builds. Sort of the opposite of wesh and meshport. Another mighty world manipulation tool like worldedit. Blazing fast.

About

Note: Voxelizer needs to be added to the "trusted mods" if "mod security" is enabled. You should always ensure that all your "trusted mods" run in a safe environment (which means that all other mods are safe as well).

Depends on modlib and cmdlib. IntelliJ IDEA with EmmyLua plugin project. Code licensed under the GPLv3 for now.

Written by Lars Mueller alias LMD or appguru(eu).

Media licenses (files in the media folder):

Logo license (logo.png): derived from character.png by Jordach (see above), same license (CC BY-SA 3.0), rendering & modifications by me (LMD)

  • GitHub - sources, issue tracking, contributing
  • Discord - discussion, chatting
  • Minetest Forum - (more organized) discussion
  • ContentDB - releases (downloading from GitHub is recommended)

Screenshots

Screenshot 1 Some Sams, using reduced palettes.

Screenshot 2 Another Sam, using the full colors.txt palette from Minetestmapper.

Screenshot 3 Same Sam, rear view.

Screenshot 4 2 mages & Ironmen (thanks to Jordach and Ginsu23 for the skins)

The used texture pack was MTUOTP by Aurailus and GamingAssociation39. Other textures seen are from Minimal Development Test or the Wool mod (wool textures by Cisoun).

Usage

All commands are executed with /vox <command> {params}. If in need for help, just do /help vox. You need the voxelizer priv to use any of the Voxelizer commands. Some commands require extra privs. Media - models, textures and nodemaps (color lookups) - is stored in <worldpath>/media. If you are unsure about which settings to use, either do some research or try it and see. Editing the placed models is recommended; Voxelizer might place a few blocks undesirably, which needs to be fixed by hand. Voxelizer needs to be added as to the trusted mods in the settings in order to be able to read textures or download files. Disabling mod security would also work but is not recommended.

Configuration

Per-player configuration commands. Configuration remains after shutdown (is persistent).

  • texture [path] - set/get the current texture (see Supported File Formats)
  • nodemap [path] - set/get the current nodemap (see Supported File Formats)
  • dithering [id] - set/get the current error diffusion dithering algorithms (specify algorithm ID)
  • color_choosing [id] - set/get current color choosing mode (best/average)
  • filtering [id] - set/get current filtering mode (nearest/bilinear)
  • placement [id] - set/get merge modes (specify mode ID)
  • model [path] - set/get the current 3D model (see Supported File Formats)
  • alpha_weighing [enable/disable] - get/enable/disable weighing colors (see color_choosing) by their alpha
  • protection_bypass [enable/disable] - get/enable/disable protection bypass (you need the priv protection_bypass to enable it)
  • precision [number] - set/get the current rasterization accuracy (integer). Note that this increases computation time quadratically. Values higher than 10 are not recommended.

Supported file formats

Textures

All file formats supported by ImageIO on your Java setup. You can find them out using the following commands :

cd ~/.minetest/mods/voxelizer/production/voxelizer
java SupportedTextureFormats

On my system (Java 11), the output was :

The supported image file formats are : JPG, jpg, tiff, bmp, BMP, gif, GIF, WBMP, png, PNG, JPEG, tif, TIF, TIFF, wbmp, jpeg

Internally, the SIF (.sif, "Simple Image File") file format (just gave it some name) is used:

  • 4 byte header : 2 times a 2 byte unsigned short, first is width, second is height
  • Followed by uncompressed image data : array of 4 byte tuples, consisting of ARGB unsigned bytes, positions in array are calculated as x + y * width
Node Map

Any valid minetestmapper-colors.txt will be accepted by this mod. The format is :

Multiple lines like [(<content_id:hex>|<nodename>) <red> <green> <blue>][#<comment>]

3D Models

Only the .obj file format is (with certain restrictions) supported. It is recommended to export your models from Blender.

Restrictions :

  • No free form geometry (vps)
  • No complex texture coordinates (vts with more than 2 coordinates given), use simple ones
  • No polygonal faces (fs with more than 3 indexes), use triangles
  • No line (l) elements
  • No material (.mtl) file usage, only a single texture
  • No smooth shading (s)
  • No normals (vn)

All of the above will be ignored whenever possible.

Export your .obj files with Blender properly by ticking the right options, as seen here :

Ticked checkboxes in Blender's "Export OBJ" dialog

So summarized, the following boxes should be ticked :

  • Apply modifiers
  • Write normals (not required)
  • Write UVs
  • Triangulate faces
  • Objects as OBJ objects

Everything else should not be ticked.

Actions

  • 1/2 - set first and second edge position, model will be placed thereafter and positions will be deleted
  • place [scale] - place model with given scale (defaults to 1)
  • download <url> [filename] - download a file from the internet using a GET request, requires voxelizer:download priv additionally. File will be downloaded to <worldpath>/media/filename. The URL filename will be taken if filename is not specified.

Configuration

JSON Configuration: <worldpath>/config/voxelizer.json Text Logs: <worldpath>/logs/voxelizer/<date>.txt Readme : <modpath/gamepath>/voxelizer/Readme.md Default Configuration : <modpath/gamepath>/voxelizer/default_config.json

{
  "max_precision" : 15,
  "download" : true,
  "defaults" : {
    "precision" : 4,
    "min_density" : 0.1,
    "dithering" : 10,
    "placement" : 1,
    "color_choosing" : 1,
    "filtering" : 1
   }
}

max_precision

Integer, maximum settable precision.

download

Boolean, whether to enable the /vox download chatcommand.

defaults

Dictionary / table, default names assigned to corresponding values. Possible names below.

min_density

Float between 0 and 1. Minimum density default.

precision

Integer > 1 and < 100. Precision default.

dithering

Default dithering algorithm ID (see /vox dithering).

placement

Default placement mode ID (see /vox placement).

color_choosing

Default color choosing algorithm ID (see /vox color_choosing).

filtering

Default filtering algorithm ID (see /vox filtering).

model / texture / nodemap

Optional default filenames. Files will be searched in world's media folder. If not given, Voxelizer falls back to default files from mod's media folder.