Building Facades

Building Facades

Normally Arnis builds walls from blocks, with the material and colour from the map data or from the regional style. With building facades, Arnis puts photos on the walls instead. There are two sources, and you pick one of them under Settings > Building Facades > Facade Source:

	Preset	Mapillary
Photos	a bundled set, picked by building type	real street-level photos of each building
Needs	nothing	a free Mapillary token
Covers	every building	buildings someone has photographed
Formats	Java 1.21.4+	photos: Java 1.21.4+, blocks: every format
Speed	fast	slow the first time, cached after that

The two are alternatives, not layers. If you turn on the preset facades while you have a Mapillary token set, the Mapillary facades are off for that run.

How the photos are shown

The photos hang on the walls as item display entities, one flat panel per wall face. Display entities can sit at any angle, so a diagonal wall gets one smooth panel instead of a staircase of blocks. The wall behind is still built from blocks in matching colours, so it looks right from far away too. The textures are packed into a resource pack in the world folder (resources.zip), which Minecraft loads with the world. If the world already had a resources.zip that Arnis didn't make, it's kept as resources.zip.bak.

Minecraft puts every block texture into one big texture atlas, and if that overflows it drops the whole resource pack. That's what Facade Detail is for: Standard stays within what every graphics card handles, High is sharper but wants a modern one on every machine that opens the world. If the panels don't fit, their resolution is lowered automatically (--facade-px sets the starting resolution, 16 pixels per block by default).

Walls that face a neighbouring building closely (party walls) only get a panel above the neighbour's roof, or none at all.

Preset facades

--building-facades

Arnis comes with a set of 113 facade photos (all CC0), compiled into the executable, so no download is needed. Each photo is tagged with the building types it suits (office, residential, warehouse, school, historic and so on) and its real size in metres.

For each building, Arnis picks a photo of the same type whose storey height fits the wall best. Neighbouring buildings get different photos, and the choice only depends on the building and its position, so generating the same area twice gives the same result. All parts of one building get the same photo.

A photo is never stretched, because windows twice as tall as a person look wrong immediately. Narrow walls show a crop, wide walls repeat the photo, and tall walls keep the ground floor once and repeat the upper storeys.

You can use your own set with --building-facades-dir: a folder with a manifest.json and the images. Have a look at assets/building-facades/ in the repository for the format.

Mapillary facades

Mapillary is a platform for street-level photos that anyone can upload. Arnis can use those photos to rebuild the actual facade of each building.

Setup

1. Create a free account and get a client token at mapillary.com/developer.
2. Paste it into Settings > Building Facades > Mapillary Token and set the facade source to Mapillary. On the command line, pass --mapillary-token or set the MAPILLARY_TOKEN environment variable. The token alone turns the feature on.

The token stays on your computer.

Area size

Downloading and processing the photos is slow. A few streets can take a quarter of an hour the first time. Because of that, Arnis only downloads new imagery for areas up to 0.1 km² during a generation. Larger areas use whatever is already cached.

To cover a bigger area, use Precompute Area in the settings on smaller pieces first. Everything is cached per wall, so a later generation that covers the same buildings picks the finished walls up straight away, even with a different area selection.

To find out if an area is worth it before you wait, run --mapillary-probe on the command line. It checks the coverage, prints what it found and exits without generating a world.

Photos or blocks

Facade Mode decides what happens with the result:

• Photos (default): the photo hangs on the wall, with matching blocks behind it. Java 1.21.4+.
• Blocks: no photo, the wall blocks are picked from the photo's colours and windows and doors are placed where the photo has them. This works for Java, Bedrock and Luanti.

Below a scale of 2 blocks per metre only the colours are used (per floor), since windows and doors can't be placed accurately at that size. Explicit material and colour tags in OSM always win over the photos.

In One World mode Mapillary facades are always built as blocks, since a new area would replace the resource pack with the photos of the area before.

How it works

src/mapillary/ is a Rust port of a Python prototype, orthofacade. Very roughly:

1. Fetch: the building footprints, and the metadata, 3D reconstructions and thumbnails of the photos around them.
2. Align: OSM outlines and Mapillary imagery drift apart by a few metres. The reconstructed point cloud is registered against the footprints, and the real wall plane is fitted from it.
3. Texture: for every wall, each photo that sees it head-on is projected onto the wall rectangle. Several views are combined with a median, which removes parked cars and people, since they move between photos and the wall doesn't.
4. Read it: windows and doors are found as patches that are darker or differently coloured than the wall (there's no object detection), rows are grouped into floor bands, and every wall gets a confidence score. Walls that aren't trustworthy enough are skipped.
5. Export per wall: a colour and class grid at one pixel per metre, plus the texture.

The downloads start as soon as the area is known, in parallel with the other data, and the result is picked up right before the buildings are built. If anything fails, the world is still generated, just without the photos.

Credits

Mapillary imagery is licensed CC BY-SA 4.0, which means the photographers have to be credited. Arnis lists every photo that was used, with its author, under License and Credits in the app, and on the command line at the end of the run. In the world, the pause menu credits mention Mapillary as well.