Command-line tool and Python library for creating isometric Minecraft renders.
mcrender is a wrapper around Mineways and Blender, which do the bulk of the work. It automates the communication between these two tools, and offers a command-line/Python interface for them.
Jump to: Installation | Usage - CLI | Usage - Python | Alternatives | Acknowledgements
mcrender requires Python 3.7+.
It is available on PyPI, and can be installed with pip:
python3 -m pip install mcrender
mcrender depends on Mineways and Blender (version >= 4.0.0), which need to be installed manually. Mineways is Windows-only, so if you're not on Windows, you will also need Wine.
mcrender has been tested with Mineways 11.0 and Blender 4.2.0, but is expected to work with any future versions with similar APIs.
In addition, mcrender needs to know how it can access these dependencies: you need to specify commands that will run Mineways and Blender on your system. It is possible to specify these commands every time you call mcrender, but it is recommended to set default commands in mcrender's config file.
The location of the config file depends on your operating system. It is shown at the bottom of the mcrender --help message.
If the config file doesn't exist, mcrender creates a default one when you run it.
The config file has two keys:
-
mineways-cmd: Command to run Mineways.
Set this to a command that will run Mineways on your system. If you run Mineways through Wine, an example command would bewine /path/to/Mineways.exe -
blender-cmd: Command to run Blender.
Set this to a command that will run Blender on your system. The default valueblenderis probably fine.
To run mcrender, use:
mcrender [options] <world path> <output path>
This will create a render of the Minecraft world at <world path>, and save it at <output path> in PNG format. (Though note that mcrender will not automatically append the .png extension to <output path>.)
You also need to specify which 3D box of the Minecraft world to render. This can be done in two ways:
- Using
--posand--size. - Using two
--posoptions: one for each corner (inclusive).
| Option | Description | Default |
|---|---|---|
-p, --pos <x> <y> <z> |
Render-box corner | |
-s, --size <x> <y> <z> |
Render-box size | |
--rotation {0,1,2,3} |
Rotation of the camera. | 0 |
--dimension <id> |
World dimension.* | overworld |
--exposure <float> |
Post-processing exposure (brightness). Can be negative. | 0 |
--trim / --no-trim |
Whether to trim the output image.** | --trim |
-f, --force |
Overwrite any existing file at the output path. | |
--mineways-cmd <cmd> |
Command to run Mineways. Overrides the config file. | |
--blender-cmd <cmd> |
Command to run Blender. Overrides the config file. | |
-v, --verbose |
Print more information. | |
-q, --quiet |
Cancel a previous --verbose. | |
--version |
Show the version and exit. | |
--help |
Show a help message and exit. |
*: Dimension options: overworld, the_nether, nether, the_end, end.
**: The render is always created at a resolution of 2048x2048 pixels, but the model may not be square. If --trim is set (which it is by default), the image is trimmed down to the model's bounding box. Otherwise, the model will be centered in the image.
mcrender -v /path/to/minecraft-world -p 0 60 0 -s 64 128 64 --rotation 1 snippet.png
The mcrender package has only one public module; everything can be imported directly from mcrender. The interface consists primarily of the following thee functions:
-
def render( output_path: str, world_path: str, x: int, y: int, z: int, size_x: int, size_y: int, size_z: int, rotation: int = 0, dimension: str = "overworld", exposure: float = 0, trim: bool = True, force: bool = False, mineways_cmd: Optional[str] = None, blender_cmd: Optional[str] = None, verbose: bool = False, )
The "main" function of mcrender. Essentially works just like the command-line interface: the parameters mirror the CLI arguments and options. If
mineways_cmdorblender_cmdis set toNone, the command from the config file will be used. -
def mineways_make_obj( output_dir_path: str, output_name: str, world_path: str, x: int, y: int, z: int, size_x: int, size_y: int, size_z: int, rotation: int = 0, dimension: str = "overworld", mineways_cmd: Optional[str] = None )
Does only the Mineways part: creates an OBJ model of a Minecraft world snippet. The output OBJ file is written to
<output_dir_path>/<output_name>.obj. Auxillary model files (like textures) are written to<output_dir_path>. -
def blender_render_obj( output_path: str, obj_path: str, exposure: float = 0, trim: bool = True, force: bool = False, blender_cmd: Optional[str] = None )
Does only the Blender part: renders an OBJ file (as created by Mineways) to a PNG image.
There's a lot that can go wrong when dealing with external programs and the filesystem. The core functions described above can raise the following exceptions:
-
MCRenderError
Base class for all mcrender exceptions. -
ConfigAccessError
Raised when the config file cannot be accessed. -
MinewaysCommandNotSetError
Raised when the Mineways command is not set. -
MinewaysLaunchError
Raised when the Mineways command cannot be launched. -
MinewaysError
Raised when Mineways returns an error. -
MinewaysBadWorldError
Raised when Mineways cannot load the world. -
BlenderCommandNotSetError
Raised when the Blender command is not set. -
BlenderLaunchError
Raised when the Blender command cannot be launched. -
BlenderError
Raised when Blender returns an error. -
OutputFileExistsError
Raised when an output file or directory already exists and cannot be overwritten.
In some circumstances, the core functions may also raise built-in exceptions such as OSError.
-
DIMENSIONS
List of supported world dimension identifiers. -
CONFIG_PATH
Path of the config file on the current operating system. -
ensure_config_file()
Creates a default config file if it doesn't exist.
Raises a ConfigAccessError if creation fails.
Note that the core functions will already call this if they need the config file.
import mcrender
mcrender.render(
"output.png",
"/path/to/minecraft-world",
0, 60, 0,
64, 128, 64
)Rendering Minecraft worlds is not a new concept. This particular tool is mainly intended for use in scripts or larger systems. It's very automatable, but not very interactive.
Advantages of mcrender compared to other rendering tools:
- Easily automatable
- No need to open Minecraft, modify it, or even install it
Disadvantages:
- Not very interactive; cannot select region in-game.
- Depends on Mineways and Blender, which must be installed separately.
Here are a few alternatives for different use cases that I came across. Disclaimer: I have not tried most of them, so these descriptions may be inaccurate.
-
Chunky
Very extensive GUI rendering system for Minecraft. Can do more than just isometric renders. -
Isometric Renders mod
A mod that allows you to render world snippets or items in-game. -
mcmap
Creates pixel art renders instead of using Minecraft textures. Has an out-of-game command-line interface similar to mcrender. -
CyclesMineways
Blender script for rendering Mineways output with Blender's cycles renderer. Compared to mcrender, does not automate the Mineways part and requires an old version of Blender (<2.80), but uses a more sophisticated renderer. -
A script from World-GAN
The main inspiration for mcrender. Automates only the Mineways part, but the repository also contains a modified version of CyclesMineways for the Blender part. No command-line interface. Note that the script somewhat confusingly refers to Mineways object creation as "rendering". -
Manual Mineways with a rendering engine (like Blender's)
Mineways creates models of Minecraft world snippets, which can be 3D printed or rendered. Using Mineways and a rending engine separately is more complex, but opens up more possibilities.
mcrender was inspired by the scripts from World-GAN, as described under Alternatives.
Blender files were created by Björn van der scheer.