Introduction

In this post, we’ll explore an experimental project — not something built for practical use, rather for exploring some technology and techniques. The goal is to create an immersive, cube-shaped map visualization using web tools and Python backend services. Specifically, we’ll use:

• FastAPI to collect map tiles and process them into cube faces.
  
• OpenCV to warp top-down map tiles into side-facing cube views.
  
• Marzipano, a web-based panorama viewer, to render a navigable, interactive map cube in the browser.

Imagine standing inside a cube where every wall is a piece of a map — north, south, east, west, and beneath your feet — while the top is left open. Users can click in different directions to navigate the map and explore surrounding areas. Along the way, hotspots display contextual information about the current tile.

While not necessarily useful as-is, this project demonstrates a variety of transferable skills: image processing, API design, dynamic frontend rendering, and 360° UI integration.

Backend: FastAPI + Image Processing

The backend is a FastAPI server that accepts requests for a particular tile (x, y, and zoom level) and cube face (front, left, right, back, and down), fetches relevant surrounding map tiles, processes them, and returns cube face images to the frontend. You can find the code for our API in this gist. You can learn more about map tiles here. There are also a handful of useful tools for exploring and visualizing map tiles, such as Sparkgeo’s Tile ID API (blog, docs) and Mapbox’s What the Tile app.

How it works:

1. Tile Fetching: Given a base tile coordinate and cube face direction, the server retrieves and merges relevant map tiles, then warps portions of the combined image to a square, and returns the image to be placed on a cube face.

In the example below, if the tile coordinate in question is x=4, y=4, z=4, and the left cube face (West) is requested, the API will request map tiles: [3, 3, 4], [3, 4, 4], and [3, 5, 4]. Our API makes requests to MapTiler’s streets-v2 tiles (free account required). The relevant tiles are then merged together for warping.

2. Image Warping: Each merged tile image is processed into a perspective view using OpenCV’s warpPerspective function, so that rectangular map image may be displayed as a single square cube face. For example, the left face of the cube is a warped view of the tiles west of the center tile. Technically, we extract an isosceles trapezoid of pixels from the three west tiles, and likewise for other directions. The down cube face is left unaltered. The top of the cube can be left open, but we generate a starry sky in the API.
   

API Request and Response:

Request: GET /tile/{z}/{x}/{y}/{f}

Response: The API returns these cube face images through a FastAPI StreamingResponse to be used in the UI.

Frontend: Marzipano-Powered Map Cube

The frontend is built with a static web page using Marzipano, a 360° panorama framework typically used for virtual tours. We repurpose it to display the map cube. You can find the code for our frontend in this gist.

Features:

• Cube Geometry: Each side face of the cube uses the warped tile images served from the backend.
  
• Navigation Hotspots: Interactive hotspots on the cube walls let users click to move to any of the eight surrounding map tiles. An info hotspot is also placed on the bottom cube face with information about the current tile.
  
• Tooltip Info: Hovering over a hotspot shows metadata about the current or target tile.
  
• Dynamic Loading: When a hotspot is clicked, the frontend requests new cube faces from the API and re-renders the scene.
  

This creates the illusion that you’re navigating through a 3D map environment, stepping from one location to the next inside a cube of maps.

Lessons and Takeaways

Though experimental, this project demonstrates several valuable techniques:

• Server-side image transformation: Using OpenCV in FastAPI for real-time processing (request, merge, warp) of imagery.
  
• REST API for spatial navigation: Structuring an API to return visual content and logical movement options based on position.
  
• 360° UI customization: Using a panoramic viewer for unconventional purposes (map exploration).
  
• Client-server integration: Decoupling backend image processing from frontend rendering in a clean, scalable way.
  

You could extend these concepts to create more practical tools — like visualizing GIS data, remote sensing previews, game maps, or location-based storytelling.

Conclusion

This experimental map cube project brings together FastAPI, OpenCV, and Marzipano in a unique way. While it’s not a production-ready tool, you might find it useful for exploring ideas in spatial interfaces, dynamic imagery, and web-based 3D visualization.

If you’re looking to stretch your skills or learn by building strange but educational things, this may appeal to you. Plus, it shows how flexible our tools can be when we take them slightly out of context.

Have ideas to build on this? Try adding elevation data, live map overlays, or multi-user navigation. The cube is just the beginning.