Film Microgenres Mapped
An interactive map of 10,000 of the most popular films on TMDb, released from 1980 onward and arranged by experiential similarity: story, mood, texture, theme, and audience perception, not genre alone.
How to read it
Every dot is one film. The atlas maps 10,000 popular TMDb movies released from 1980 onward. At the widest zoom, it shows broad cinematic territories: crime worlds, family animation, dystopian futures, romance and becoming, survival dread, mythic spectacle, and more.
Zoom in and those territories split into neighborhoods. Zoom further and neighborhoods reveal micro clusters: smaller groups of films with unusually similar themes, tone, story mechanics, or audience vibe.
Search for a film, click a dot, or follow a nearest neighbor to move through the map. The side panel shows the selected movie's macro region, neighborhood, micro cluster, and closest semantic neighbors.
Visual distance is a guide, not the whole truth. Nearest neighbors are calculated in the full semantic embedding space; the map is a browser-rendered projection designed to make that high-dimensional structure explorable.
Inspiration
The idea started with the pleasure of Spotify microgenres: those oddly specific labels that make taste feel less like a dropdown menu and more like a living cultural map.
Movies already have genres, but genre is blunt. A film can be comedy, horror, romance, or sci-fi and still belong to a stranger experiential family: lonely future intimacy, corporate satire, cozy mystery, survival dread, mythic spectacle, suburban paranoia, or slacker noir.
The Film Atlas asks whether cinema can be explored the way people often discover music: by texture, mood, story shape, and felt similarity. It is not a replacement for genre. It is a second map underneath it.
How I built it
The finished map looks simple: dots, territories, labels, search, and nearest neighbors. The hard part was making those pieces mean the same thing.
This project became less about drawing a pretty embedding and more about building a trustworthy semantic geography: a system where the data model, labels, borders, and user interface all describe the same underlying structure.
01
The first version used the official TMDb API to build controlled movie profiles from titles, overviews, genres, keywords, and short review-language snippets.
That made the project publishable: no Letterboxd scraping, no IMDb review scraping, no private datasets, and no raw review text exposed in the browser. But the early profiles were too thin. They produced some good neighbors, but not enough depth for the kind of vibe map the interface wanted.
02
The stronger version combined multiple public signals: TMDb metadata, MovieLens Tag Genome relevance scores, MPST plot tags and synopses, controlled synopsis texture, and light review language.
The key lesson was that more text was not automatically better. Heavy review text added noise. Title-heavy profiles created leakage. The best representation balanced plot, theme, tone, audience perception, and genre without letting any single source dominate.
Each film became a semantic profile: a compact description of what the movie is about, how it feels, and what viewers tend to associate with it.
03
Each semantic profile was embedded into a high-dimensional vector. Nearest neighbors are calculated there, where the semantic signal is strongest. The visible map is a projection. It is useful for exploration, but it is not treated as the source of truth.
That distinction mattered. A raw 2D projection can make good semantic neighbors appear far apart, or make nearby dots look more related than they really are. The atlas needed to be visually readable without pretending that screen distance explains everything.
04
The biggest early failure was structural. Macro regions, neighborhoods, and micro clusters originally behaved like separate layers that looked nested in the UI but were not always truly nested in the data.
The final system uses strict hierarchical clustering: cluster the full set into macro regions, cluster within each macro region into neighborhoods, then cluster within each neighborhood into micro clusters. That means every film has one real path through the atlas: macro region -> neighborhood -> micro cluster.
The geography is not just a visual effect. It is enforced by the data model.
05
The labels are the product surface. They are how people understand the map.
I used LLM-assisted labeling to generate names for regions, neighborhoods, and micro clusters, but the goal was not to blindly accept whatever sounded clever. Labels had to be vivid enough to feel human and specific enough to be useful.
The guiding phrase became: poetic but accountable. A good label should be memorable, but it should also be supported by representative films, tags, cluster evidence, and nearest-neighbor behavior.
06
The interface exposed problems the pipeline alone could hide. Some labels overpromised. Some borders implied relationships that were not true. Some nearest neighbors were semantically good but visually surprising. Some map experiments looked beautiful but were less honest.
Search, selected-film panels, expandable cluster cards, and nearest-neighbor links became more than UI features. They became audit tools.
The frontend became a cartography problem: how do you show high-dimensional semantic relationships in a way that feels readable, stable, and honest?
Technical implementation
The production page is intentionally simple: Astro serves sanitized JSON, and a custom Canvas renderer draws the atlas in the browser. There is no recommendation API, no model call, and no private data dependency on the public page. All of the expensive work happens ahead of time in an offline pipeline.
TMDb is the foundation for movie identity and metadata: titles, release years, overviews, genres, keywords, taglines, popularity signals, and stable IDs for matching. The MovieLens Tag Genome adds structured audience-perception signal through tag relevance scores, which helps the atlas capture vibe, tone, theme, and style more directly than genre fields alone. MPST contributes plot tags and controlled synopsis texture, giving thin TMDb summaries more narrative shape without letting long synopses overwhelm the representation.
Those sources are combined into semantic profiles: compact, source-balanced descriptions of what each film is about, how it feels, and what viewers tend to associate with it. The profiles are embedded with OpenAI embeddings, then used in two separate ways. Nearest neighbors are computed in the full embedding space, where semantic similarity is strongest. Clustering is also performed in embedding space, using a strict hierarchy: macro regions first, neighborhoods inside each macro region, and micro clusters inside each neighborhood.
Labels are generated with LLM assistance, but treated as a reviewable product layer rather than ground truth. The labeling pass uses cluster evidence, representative films, tags, and neighbor behavior to make names vivid enough for a public-facing atlas while keeping them inspectable. The final export keeps only what the browser needs: movie display fields, points, hierarchy records, labels, territory layouts, and neighbor shards. API keys, raw reviews, raw embeddings, and private experiment artifacts stay out of the static site.
Experiments and tradeoffs
| Area | Tradeoff | Final choice |
|---|---|---|
| Data | Richer sources improved semantic texture, but scraped review ecosystems would weaken the public data story. | Use TMDb plus public MovieLens and MPST signals; avoid Letterboxd and IMDb scraping. |
| Profiles | More text was not automatically better; title-heavy or review-heavy profiles could create leakage and noise. | Build balanced semantic profiles from plot, theme, tone, tags, and controlled review/synopsis texture. |
| Clustering | Flat clusters were easier to generate, but made the UI imply a hierarchy the data did not fully support. | Use a strict macro region -> neighborhood -> micro cluster hierarchy so each film has one real atlas path. |
| Methods | A beautiful 2D projection can hide or distort high-dimensional relationships. | Compute neighbors and clusters in full embedding space; use the map as an explorable projection. |
| Labels | Purely literal labels felt flat; purely poetic labels could overstate the evidence. | Use LLM-assisted labels that are vivid, inspectable, and accountable to cluster evidence. |
| Validation | Semantic quality is partly subjective, so a single metric would be false confidence. | Combine structural scans, spot checks, large audits, failure-set rechecks, and browser QA. |
| UI | More explanation in the map surface added cognitive weight. | Keep the interaction lightweight and move deeper methodology lower on the page. |
| Frontend | A backend could make exploration more dynamic, but would add operational and privacy surface area. | Ship a static Astro + Canvas experience backed by sanitized JSON and lazy neighbor shards. |
Validation
A semantic map is partly subjective, so validation could not be purely mathematical. I used a mix of known-film spot checks, cluster-label review, structural scans, large LLM-assisted audits, and targeted repairs.
The technical checks focused on whether the hierarchy was real, not merely visual: every movie needed one valid macro region, one neighborhood inside that macro region, and one micro cluster inside that neighborhood. The export was also scanned for duplicate path labels, missing cluster assignments, malformed neighbor lists, and accidental leakage of private artifacts.
Nearest-neighbor quality was checked separately from screen position. That mattered because the map is a projection: a point can look distant on the canvas while still being close in the full embedding space. Validation therefore compared selected films against their semantic neighbors, cluster memberships, labels, and visible territory placement as separate signals.
Browser QA became part of the validation loop too. Search, zoom, selected-film panels, expandable cluster cards, labels, territory boundaries, and console health were all inspected against the sanitized static export so the public page stayed aligned with the offline pipeline.
The final public export contains 10,000 films, 946 labels, 16 macro regions, 180 neighborhoods, and 750 micro clusters. The hierarchy scan found no duplicate macro region/neighborhood/micro cluster path labels, and the browser export contains no API keys, raw reviews, or embeddings.
The largest audit before targeted repair scored 9,633 pass, 336 mixed, and 31 fail. After repair rules were applied to the failure set, the recheck found 22 pass, 9 mixed, and 0 fail. I treated audit results as directional quality checks, not as objective truth: evidence that the atlas is useful and inspectable, not proof of perfect classification.
The project moved from "more data will fix it" to "the structure has to be true." It moved from flat cluster labels to telescoping region names, from a raw scatterplot to a semantic atlas, and from one-off model output to an audited public product.
Official and public data sources, balanced semantic profiles, full-space nearest-neighbor computation, strict hierarchy, human-reviewable labels, targeted repairs, and browser QA made the system legible without requiring a backend.
Heavy review text, title-heavy embeddings, non-nested clustering, purely quantitative cluster selection, and decorative map borders all created attractive but less trustworthy versions of the atlas.
Movie metadata is sourced from TMDB. This product uses the TMDB API but is not endorsed or certified by TMDB.