{"id":16160920,"url":"https://github.com/spoutn1k/mcmap","last_synced_at":"2025-11-17T15:30:56.506Z","repository":{"id":37802597,"uuid":"948139","full_name":"spoutn1k/mcmap","owner":"spoutn1k","description":"Pixel-art map visualizer for Minecraft. Maps are drawn from an isometric perspective.","archived":false,"fork":false,"pushed_at":"2024-04-02T18:11:51.000Z","size":4106,"stargazers_count":312,"open_issues_count":11,"forks_count":45,"subscribers_count":15,"default_branch":"NBT19133","last_synced_at":"2024-10-17T07:05:57.513Z","etag":null,"topics":["linux","macos","minecraft","minecraft-map","openmp","pixel-art","qt","threading","windows"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spoutn1k.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"ko_fi":"spoutn1k"}},"created_at":"2010-09-29T11:28:08.000Z","updated_at":"2024-09-10T18:56:43.000Z","dependencies_parsed_at":"2023-02-16T02:16:11.201Z","dependency_job_id":"a9000a4f-ec7a-41c6-8414-ec19d0131610","html_url":"https://github.com/spoutn1k/mcmap","commit_stats":{"total_commits":660,"total_committers":24,"mean_commits":27.5,"dds":"0.19545454545454544","last_synced_commit":"9e626f1a76bfe9f9cdbadd7cb82754ffcc77f008"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spoutn1k%2Fmcmap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spoutn1k%2Fmcmap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spoutn1k%2Fmcmap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spoutn1k%2Fmcmap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spoutn1k","download_url":"https://codeload.github.com/spoutn1k/mcmap/tar.gz/refs/heads/NBT19133","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247353745,"owners_count":20925329,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["linux","macos","minecraft","minecraft-map","openmp","pixel-art","qt","threading","windows"],"created_at":"2024-10-10T02:06:17.254Z","updated_at":"2025-11-17T15:30:51.481Z","avatar_url":"https://github.com/spoutn1k.png","language":"C++","readme":"# `mcmap` - Isometric map visualizer\n\n![](https://img.shields.io/badge/version-1.16.5-success)\n![](https://img.shields.io/badge/version-1.17-success)\n![](https://img.shields.io/badge/version-1.18.1-success)\n![](https://img.shields.io/badge/version-1.19.4-success)\n![](https://img.shields.io/badge/version-1.20.1-success)\n\n*Original project by Simon Rettberg. All the credit goes to him for the idea and vision.*\n\n`mcmap` is a tool allowing you to create isometric renders of your Minecraft save file.\n\n![sample](assets/sample.png)\n\nThis project is under __heavy__ development, but compatible with newer versions of Minecraft.\n\n## Usage\n\n### Basic invocation\n\n```\nmcmap \u003coptions\u003e path/to/\u003cyour save\u003e\n```\n\nThe standard save path is different between OSes:\n- On Linux, it is `$HOME/.minecraft/saves`;\n- On macOS, under `~/Library/Application\\ Support/minecraft/saves`;\n- On Windows, the standard path is `%AppData%\\.minecraft\\saves`. If using [Ubuntu on Windows](https://ubuntu.com/tutorials/tutorial-ubuntu-on-windows#1-overview), the path to access the save folder is the following: `/mnt/c/\u003cYour user\u003e/AppData/Roaming/.minecraft/saves`.\n\nNative Windows is now supported.\nPre-compiled binaries can be downloaded from the [releases page](https://github.com/spoutn1k/mcmap/releases).\nFor now, the program can only be used via `terminal`/`powershell` on Linux/Macos or Windows respectively.\n\nAn experimental GUI is available for Windows and can be downloaded [here](https://github.com/spoutn1k/mcmap/discussions/63).\n\n### Options\n\n| Name                         | Description                                                                                              |\n|------------------------------|----------------------------------------------------------------------------------------------------------|\n|`-from X Z`                   |sets the coordinates of the block to start rendering at                                                   |\n|`-to X Z`                     |sets the coordinates of the block to end rendering at                                                     |\n|`-center X Z`                 |sets the center of a circular render                                                                      |\n|`-radius VAL`                 |sets the radius of a circular render                                                                      |\n|`-min/max VAL`                |minimum/maximum Y index (height) of blocks to render                                                      |\n|`-file NAME`                  |sets the output filename to 'NAME'; default is `./output.png`                                             |\n|`-colors NAME`                |sets the custom color file to 'NAME'                                                                      |\n|`-nw` `-ne` `-se` `-sw`       |controls which direction will point to the top corner; North-West is default                              |\n|`-marker x z color`           |draw a marker at `x` `z` of color `color` in `red`,`green`,`blue` or `white`; can be used up to 256 times |\n|`-nowater`                    |do not render water                                                                                       |\n|`-nobeacons`                  |do not render beacon beams                                                                                |\n|`-shading`                    |toggle shading (brightens blocks depending on height)                                                     |\n|`-lighting`                   |toggle lighting (brightens blocks depending on light)                                                     |\n|`-nether`                     |render the nether                                                                                         |\n|`-end`                        |render the end                                                                                            |\n|`-dim[ension] [namespace:]id` |render a dimension by namespaced ID                                                                       |\n|`-mb VAL`                     |maximum memory to use at once (default 3.5G, increase for large maps if you have the ram)                 |\n|`-fragment VAL`               |render terrain in regions of the specified size (default 1024x1024 blocks)                                |\n|`-tile VAL`                   |generate split output in square tiles of the specified size (in pixels) (default 0, disabled)             |\n|`-padding`                    |padding around the final image, in pixels (default: 5)                                                    |\n|`-h[elp]`                     |display an option summary                                                                                 |\n|`-v[erbose]`                  |toggle debug mode                                                                                         |\n|`-dumpcolors`                 |dump a json with all defined colors                                                                       |\n\n*Note: Currently you need both `-from` and `-to` OR `-center` and `-radius` to define bounds.*\n\n#### Tips\n\n`mcmap` will render the terrain in batches using all the threads of your computer. Unfortunately, when those batches merge, some artifacts are created: lines appear in oceans where the merge was operated.\n\nUse `-fragment` with a bigger value to limit the amount of batches and thus of artifacts. This is limited by the available memory, as rendering a whole map iin one go may require 10+ gigabytes of ram.\n\nUse `-fragment` with a lower value to increase performance. Fragments of 256x256 and 512x512 blocks are really efficient.\n\n## Color file format\n\n`mcmap` supports changing the colors of blocks. To do so, prepare a custom color file by editing the output of `mcmap -dumpcolors`, and pass it as an argument using the `-colors` argument.\n\nThe accepted format is a `json` file, with a specific structure.\nThe root contains a list of [block IDs](https://minecraft.wiki/w/Java_Edition_data_values#Blocks) to modify, with the namespace prefix, such as `namespace:block`.\n\n#### Simple block\n\nTo define a color for a simple, regular block, provide an entry in a JSON file.\nThe color format is a [hexadecimal color code](https://htmlcolorcodes.com/).\nIf the alpha is not specified, it is assumed to be opaque.\n\n```\n\"namespace:block\": #rrggbbaa (or #rrggbb)\n```\n\nExamples:\n```\n{\n    \"minecraft:dirt\":   #7b573b,\n    \"minecraft:ice\":    #7dadff9f, \n    ...\n}\n```\n\n#### Complex block\n\nSome blocks are better looking when drawn in a specific way.\nTo specify that a block has to be drawn differently, you have to provide a `json` structure with the following fields:\n\n```\n\"namespace:block\": {\n    \"type\":     \u003cBlockType\u003e,\n    \"color\":    \"#rrggbbaa\",\n    \"accent\":   \"#rrggbbaa\" (Optional)\n}\n```\n\nThe available available block types are:\n\n|Name|Appearance|Accent support|\n|-|-|-|\n|`Full`|Default. Full-block.|No|\n|`Hide`|Do not render the block entirely.|No|\n|`Clear`|This block is optimized for transparent block in large quantities, such as glass and water. The top of the block is not rendered, making for a smooth surface when blending blocks together.|No|\n|`Thin`|Will color only the top of the block underneath. Used for snow, rails, pressure plates.|No|\n|`Slab`|Half block.|No|\n|`Stair`|Renders a stair block.|No|\n|`Rod`|A slimmer block, used for fences and walls.|No|\n|`Wire`|Small dot on the floor, used for tripwire and redstone.|No|\n|`Head`|Smaller block, also used for pots, pickles, and mushrooms.|No|\n|`Plant`|Used in a variety of cases, renders a leaf-like block.|No|\n|`UnderwaterPlant`|Same as `Plant`, but the air is water-colored. Used for sea-grass and kelp.|No|\n|`Fire`|Fire-like. Used for fire.|No|\n|`Beam`|Internal block type, used for markers and beacon beams.|No|\n|`Torch`|Three pixels in a vertical line, with the top pixel rendered with the accent color.|Yes|\n|`Ore`|Block with veins of color. The vein is rendered with the accent color.|Yes|\n|`Grown`|Blocks that have a different layer on top. Grass, nylium, etc. The top layer is rendered with the accent color.|Yes|\n|`Log`|Directionnal block, to render logs/pillars as close as possible. The center of the pillar is rendered with the accent color. Used for logs, pillars, basalt.|Yes|\n|`Lamp`|Conditionnal block, to render redstone lamps. If lit, rendered with accent color.|Yes|\n\n__NOTE__: Waterlogged blocks will be rendered within water instead of air by default according to their blockstates. However, sea-grass and kelp are hardcoded to be underwater and their blockstates won't reflect this, so they have to be defined as `UnderwaterPlants`.\n\nExamples:\n\n```\n{\n    \"minecraft:dirt\":   \"#7b573b\",  // Full block with solid color\n\n    \"minecraft:grass_block\": {\n        \"type\":     \"Grown\",        // Use a special block type\n        \"accent\":   \"#4c7a40\",      // Accent supported for `Grown`\n        \"color\":    \"#7b573b\"\n    },\n\n    \"minecraft:water\": {\n        \"type\": \"Clear\"\n        \"color\": \"#0734c832\",       // Transparency enabled\n    },\n}\n```\n\n## Tiled output\n\nUsing the `-tile` options with a non-zero value triggers the split output. A folder will be created with the following format:\n```\n$ ls output\n0    104  15  21  28  34  40  47  53  6   66  72  79  85  91  98\n1    105  16  22  29  35  41  48  54  60  67  73  8   86  92  99\n10   106  17  23  3   36  42  49  55  61  68  74  80  87  93  mapinfo.json\n100  11   18  24  30  37  43  5   56  62  69  75  81  88  94\n101  12   19  25  31  38  44  50  57  63  7   76  82  89  95\n102  13   2   26  32  39  45  51  58  64  70  77  83  9   96\n103  14   20  27  33  4   46  52  59  65  71  78  84  90  97\n```\n\nTo view the generated map, open the HTML file in `contrib/leaflet/index.html`. A file dialog will be present; give it the above `mapinfo.json` to load the map.\n\n## Compilation\n\n`mcmap` depends on the [`zlib`](https://zlib.net/), [`PNG`](http://www.libpng.org/pub/png/libpng.html), [`fmt`](https://fmt.dev/latest/index.html) and [`spdlog`](https://github.com/gabime/spdlog) libraries.\nDevelopment was made using `gcc` version 10, and can be compiled with `gcc` 8 or later or `clang` 10 or later.\nConfiguration is done using `CMake`.\n\n#### Linux\n\nGetting the libraries depends on your distribution:\n\n- Ubuntu: `apt update \u0026\u0026 apt install git make g++ libpng-dev cmake libspdlog-dev`;\n- Archlinux: `pacman -S --needed git gcc make cmake libpng spdlog fmt`.\n\nThen get the code and compile:\n```\ngit clone https://github.com/spoutn1k/mcmap\nmkdir -p mcmap/build \u0026\u0026 cd mcmap/build\ncmake ..\nmake -j\n```\n\n#### macOS\n\nIn an Apple environment, you need a developer toolkit recent enough, with the version of `g++ --version` superior to 10. \n\nUsing [`brew`](https://brew.sh/):\n```\nbrew install libpng libomp \u003cfmt/spdlog package names\u003e\ngit clone https://github.com/spoutn1k/mcmap\nmkdir -p mcmap/build \u0026\u0026 cd mcmap/build\ncmake ..\nmake -j\n```\n\n#### Windows\n\n`mcmap` was successfully compiled for Windows Visual C++ 19 and `nmake`.\nAs there is no package manager on Windows, [`libpng`](http://www.libpng.org/pub/png/libpng.html) and [`zlib`](https://zlib.net/) need to be compiled/installed manually.\nIf compiling the GUI version, you will also need [`Qt`](https://www.qt.io/download).\n\nOnce those are installed, configure `mcmap` following this template:\n```\ncmake .. -G \"NMake Makefiles\" -DCMAKE_BUILD_TYPE=Release -DSTATIC_BUILD=1^\n  -DQt5_DIR=\u003cpath to qt\u003e\\lib\\cmake\\Qt5^\n  -Dfmt_DIR=\u003cpath to fmt\u003e\\lib\\cmake\\fmt^\n  -Dspdlog_DIR=\u003cpath to spdlog\u003e\\lib\\cmake\\spdlog^\n  -DPNG_LIBRARY=\u003cpath to libpng\u003e\\lib\\libpng16_static.lib^\n  -DZLIB_LIBRARY=\u003cpath to zlib\u003e\\lib\\zlibstatic.lib\n```\n\nYou can also download and set up [Ubuntu on windows](https://ubuntu.com/tutorials/tutorial-ubuntu-on-windows#1-overview) then the steps are the same as Linux/Ubuntu.\n\n## Troubleshooting\n\n### Compilation fails\n\nCheck `g++ --version`. Supported versions are at least 8.0.0.\nIf your version is not up to date, install a more recent one using your package manager.\nYou will have access to the new version using `g++-Y` with Y being the version number.\nCompile using `CXX=g++-Y make`.\n\n### Compilation fails complaining about OMP something\n\nTry compiling with `OPENMP=NOTHXM8 make`.\nThis disables the underlying threading code, so performance may drop.\n\n### Output has lines in the ocean\n\nThis is due to the merging algorithm.\nTry increasing the split size with the `-fragment` option, or change the color of the water block to use the `Full` block type to make it less noticeable.\n","funding_links":["https://ko-fi.com/spoutn1k"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspoutn1k%2Fmcmap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspoutn1k%2Fmcmap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspoutn1k%2Fmcmap/lists"}