# mcrender - Automatable Minecraft rendering
Command-line tool and Python library for creating isometric Minecraft renders.
mcrender is a wrapper around [Mineways](https://www.realtimerendering.com/erich/minecraft/public/mineways/) and [Blender](https://www.blender.org/), 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](#installation) | [Usage - CLI](#usage---cli) | [Usage - Python](#usage---python) | [Alternatives](#alternatives) | [Acknowledgements](#acknowledgements)
## Installation
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](https://www.realtimerendering.com/erich/minecraft/public/mineways/) and [Blender](https://www.blender.org/) (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](https://www.winehq.org/).
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 be `wine /path/to/Mineways.exe`
- `blender-cmd`: Command to run Blender.\
Set this to a command that will run Blender on your system. The default value `blender` is probably fine.
## Usage - CLI
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:
1. Using `--pos` and `--size`.
2. Using two `--pos` options: one for each corner (inclusive).
### Options
| 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.
### Example usage
```
mcrender -v /path/to/minecraft-world -p 0 60 0 -s 64 128 64 --rotation 1 snippet.png
```
## Usage - Python
### Core functions
The `mcrender` package has only one public module; everything can be imported directly from `mcrender`. The interface consists primarily of the following thee functions:
- ```python
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](#usage---cli): the parameters mirror the CLI arguments and options.
If `mineways_cmd` or `blender_cmd` is set to `None`, the command from the config file will be used.
- ```python
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>`.
- ```python
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.
### Exceptions
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`.
### Miscellaneous
- `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.
### Example usage
```python
import mcrender
mcrender.render(
"output.png",
"/path/to/minecraft-world",
0, 60, 0,
64, 128, 64
)
```
## Alternatives
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](https://chunky-dev.github.io/docs/)\
Very extensive GUI rendering system for Minecraft. Can do more than just isometric renders.
- [Isometric Renders mod](https://www.curseforge.com/minecraft/mc-mods/isometric-renders)\
A mod that allows you to render world snippets or items in-game.
- [mcmap](https://github.com/spoutn1k/mcmap)\
Creates pixel art renders instead of using Minecraft textures. Has an out-of-game command-line interface similar to mcrender.
- [CyclesMineways](https://github.com/JMY1000/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](https://github.com/Mawiszus/World-GAN/blob/main/minecraft/level_renderer.py)\
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](https://www.realtimerendering.com/erich/minecraft/public/mineways/) with a rendering engine (like [Blender](https://www.blender.org/)'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.
## Acknowledgements
mcrender was inspired by the scripts from [World-GAN](https://github.com/Mawiszus/World-GAN), as described under [Alternatives](#alternatives).
Blender files were created by [Björn van der scheer](https://bluespike.artstation.com/).
Raw data
{
"_id": null,
"home_page": "https://github.com/avdstaaij/mcrender",
"name": "mcrender",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.7",
"maintainer_email": null,
"keywords": "Minecraft, Mineways, Blender, rendering, isometric, 3D, 3D modeling, 3D rendering, cli, automation",
"author": "Arthur van der Staaij",
"author_email": "arthurvanderstaaij@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5e/06/631743256d1b909cd1124cf9a746c4d1726a4ac9e7abb7a8363681d0a13a/mcrender-2.0.0.tar.gz",
"platform": null,
"description": "# mcrender - Automatable Minecraft rendering\n\n\n\nCommand-line tool and Python library for creating isometric Minecraft renders.\n\nmcrender is a wrapper around [Mineways](https://www.realtimerendering.com/erich/minecraft/public/mineways/) and [Blender](https://www.blender.org/), which do the bulk of the work. It automates the communication between these two tools, and offers a command-line/Python interface for them.\n\nJump to: [Installation](#installation) | [Usage - CLI](#usage---cli) | [Usage - Python](#usage---python) | [Alternatives](#alternatives) | [Acknowledgements](#acknowledgements)\n\n\n## Installation\n\nmcrender requires Python 3.7+.\nIt is available on PyPI, and can be installed with `pip`:\n```\npython3 -m pip install mcrender\n```\n\nmcrender depends on [Mineways](https://www.realtimerendering.com/erich/minecraft/public/mineways/) and [Blender](https://www.blender.org/) (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](https://www.winehq.org/).\n\nmcrender has been tested with Mineways 11.0 and Blender 4.2.0, but is expected to work with any future versions with similar APIs.\n\nIn 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.\nIt is possible to specify these commands every time you call mcrender, but it is recommended to set default commands in mcrender's config file.\n\nThe location of the config file depends on your operating system. It is shown at the bottom of the `mcrender --help` message.\nIf the config file doesn't exist, mcrender creates a default one when you run it.\n\nThe config file has two keys:\n- `mineways-cmd`: Command to run Mineways.\\\n Set this to a command that will run Mineways on your system. If you run Mineways through Wine, an example command would be `wine /path/to/Mineways.exe`\n\n- `blender-cmd`: Command to run Blender.\\\n Set this to a command that will run Blender on your system. The default value `blender` is probably fine.\n\n\n## Usage - CLI\n\nTo run mcrender, use:\n\n```\nmcrender [options] <world path> <output path>\n```\n\nThis 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>`.)\n\nYou also need to specify which 3D box of the Minecraft world to render. This can be done in two ways:\n1. Using `--pos` and `--size`.\n2. Using two `--pos` options: one for each corner (inclusive).\n\n### Options\n| Option | Description | Default |\n|--------------------------|---------------------------------------------------------|-------------|\n| `-p, --pos <x> <y> <z>` | Render-box corner | |\n| `-s, --size <x> <y> <z>` | Render-box size | |\n| `--rotation {0,1,2,3}` | Rotation of the camera. | 0 |\n| `--dimension <id>` | World dimension.* | `overworld` |\n| `--exposure <float>` | Post-processing exposure (brightness). Can be negative. | 0 |\n| `--trim / --no-trim` | Whether to trim the output image.** | `--trim` |\n| `-f, --force` | Overwrite any existing file at the output path. | |\n| `--mineways-cmd <cmd>` | Command to run Mineways. Overrides the config file. | |\n| `--blender-cmd <cmd>` | Command to run Blender. Overrides the config file. | |\n| `-v, --verbose` | Print more information. | |\n| `-q, --quiet` | Cancel a previous --verbose. | |\n| `--version` | Show the version and exit. | |\n| `--help` | Show a help message and exit. | |\n\n\n*: Dimension options: `overworld`, `the_nether`, `nether`, `the_end`, `end`.\n\n**: 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.\n\n### Example usage\n```\nmcrender -v /path/to/minecraft-world -p 0 60 0 -s 64 128 64 --rotation 1 snippet.png\n```\n\n\n## Usage - Python\n\n### Core functions\n\nThe `mcrender` package has only one public module; everything can be imported directly from `mcrender`. The interface consists primarily of the following thee functions:\n\n- ```python\n def render(\n output_path: str,\n world_path: str,\n x: int,\n y: int,\n z: int,\n size_x: int,\n size_y: int,\n size_z: int,\n rotation: int = 0,\n dimension: str = \"overworld\",\n exposure: float = 0,\n trim: bool = True,\n force: bool = False,\n mineways_cmd: Optional[str] = None,\n blender_cmd: Optional[str] = None,\n verbose: bool = False,\n )\n ```\n The \"main\" function of mcrender. Essentially works just like the [command-line interface](#usage---cli): the parameters mirror the CLI arguments and options.\n If `mineways_cmd` or `blender_cmd` is set to `None`, the command from the config file will be used.\n\n- ```python\n def mineways_make_obj(\n output_dir_path: str,\n output_name: str,\n world_path: str,\n x: int,\n y: int,\n z: int,\n size_x: int,\n size_y: int,\n size_z: int,\n rotation: int = 0,\n dimension: str = \"overworld\",\n mineways_cmd: Optional[str] = None\n )\n ```\n Does only the Mineways part: creates an OBJ model of a Minecraft world snippet.\n The output OBJ file is written to `<output_dir_path>/<output_name>.obj`.\n Auxillary model files (like textures) are written to `<output_dir_path>`.\n\n- ```python\n def blender_render_obj(\n output_path: str,\n obj_path: str,\n exposure: float = 0,\n trim: bool = True,\n force: bool = False,\n blender_cmd: Optional[str] = None\n )\n ```\n Does only the Blender part: renders an OBJ file (as created by Mineways) to a PNG image.\n\n\n### Exceptions\n\nThere'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:\n\n- `MCRenderError`\\\n Base class for all mcrender exceptions.\n\n- `ConfigAccessError`\\\n Raised when the config file cannot be accessed.\n\n- `MinewaysCommandNotSetError`\\\n Raised when the Mineways command is not set.\n\n- `MinewaysLaunchError`\\\n Raised when the Mineways command cannot be launched.\n\n- `MinewaysError`\\\n Raised when Mineways returns an error.\n\n- `MinewaysBadWorldError`\\\n Raised when Mineways cannot load the world.\n\n- `BlenderCommandNotSetError`\\\n Raised when the Blender command is not set.\n\n- `BlenderLaunchError`\\\n Raised when the Blender command cannot be launched.\n\n- `BlenderError`\\\n Raised when Blender returns an error.\n\n- `OutputFileExistsError`\\\n Raised when an output file or directory already exists and cannot be overwritten.\n\nIn some circumstances, the core functions may also raise built-in exceptions such as `OSError`.\n\n\n### Miscellaneous\n\n- `DIMENSIONS`\\\n List of supported world dimension identifiers.\n\n- `CONFIG_PATH`\\\n Path of the config file on the current operating system.\n\n- `ensure_config_file()`\\\n Creates a default config file if it doesn't exist.\\\n Raises a ConfigAccessError if creation fails.\\\n Note that the core functions will already call this if they need the config file.\n\n### Example usage\n```python\nimport mcrender\n\nmcrender.render(\n \"output.png\",\n \"/path/to/minecraft-world\",\n 0, 60, 0,\n 64, 128, 64\n)\n```\n\n\n## Alternatives\n\nRendering 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.\n\nAdvantages of mcrender compared to other rendering tools:\n- Easily automatable\n- No need to open Minecraft, modify it, or even install it\n\nDisadvantages:\n- Not very interactive; cannot select region in-game.\n- Depends on Mineways and Blender, which must be installed separately.\n\n 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.\n\n- [Chunky](https://chunky-dev.github.io/docs/)\\\n Very extensive GUI rendering system for Minecraft. Can do more than just isometric renders.\n\n- [Isometric Renders mod](https://www.curseforge.com/minecraft/mc-mods/isometric-renders)\\\n A mod that allows you to render world snippets or items in-game.\n\n- [mcmap](https://github.com/spoutn1k/mcmap)\\\n Creates pixel art renders instead of using Minecraft textures. Has an out-of-game command-line interface similar to mcrender.\n\n- [CyclesMineways](https://github.com/JMY1000/CyclesMineways/)\\\n 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.\n\n- [A script from World-GAN](https://github.com/Mawiszus/World-GAN/blob/main/minecraft/level_renderer.py)\\\n 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\".\n\n- Manual [Mineways](https://www.realtimerendering.com/erich/minecraft/public/mineways/) with a rendering engine (like [Blender](https://www.blender.org/)'s)\\\n 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.\n\n\n## Acknowledgements\n\nmcrender was inspired by the scripts from [World-GAN](https://github.com/Mawiszus/World-GAN), as described under [Alternatives](#alternatives).\n\nBlender files were created by [Bj\u00f6rn van der scheer](https://bluespike.artstation.com/).\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Command-line tool and Python library for creating isometric Minecraft renders with Mineways and Blender.",
"version": "2.0.0",
"project_urls": {
"Bug Reports": "https://github.com/avdstaaij/mcrender/issues",
"Homepage": "https://github.com/avdstaaij/mcrender",
"Source": "https://github.com/avdstaaij/mcrender"
},
"split_keywords": [
"minecraft",
" mineways",
" blender",
" rendering",
" isometric",
" 3d",
" 3d modeling",
" 3d rendering",
" cli",
" automation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "05665758c195acdb6d7e2fc4fbd0088e1d58db3c93ffe9fc42208d68ea1d0f5d",
"md5": "7051db004a1c879a4d66bdebf53b3898",
"sha256": "3963faee3de204d3e3a768d28475b79494e6f2d98ecfb7e6756415d55d9d7f04"
},
"downloads": -1,
"filename": "mcrender-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7051db004a1c879a4d66bdebf53b3898",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.7",
"size": 158442,
"upload_time": "2024-08-05T22:57:47",
"upload_time_iso_8601": "2024-08-05T22:57:47.921995Z",
"url": "https://files.pythonhosted.org/packages/05/66/5758c195acdb6d7e2fc4fbd0088e1d58db3c93ffe9fc42208d68ea1d0f5d/mcrender-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5e06631743256d1b909cd1124cf9a746c4d1726a4ac9e7abb7a8363681d0a13a",
"md5": "58582c6da983b28da7b6322e34fda452",
"sha256": "c3c1119626984ac32fac35a71d4a2de2d0385aa43d45eb7ffa3f01dcc20892e4"
},
"downloads": -1,
"filename": "mcrender-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "58582c6da983b28da7b6322e34fda452",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.7",
"size": 160048,
"upload_time": "2024-08-05T22:57:49",
"upload_time_iso_8601": "2024-08-05T22:57:49.996098Z",
"url": "https://files.pythonhosted.org/packages/5e/06/631743256d1b909cd1124cf9a746c4d1726a4ac9e7abb7a8363681d0a13a/mcrender-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-05 22:57:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "avdstaaij",
"github_project": "mcrender",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "mcrender"
}
JSON
