Palette Walk: An Open-Source Experiment Using K-means Clustering to Generate Outdoor Observation Cards

A Counterintuitive Design Goal: Make Screen Time the Shortest Part of the Experience

In a crowded field of AI applications, most products are designed to keep users glued to their screens. Palette Walk takes the opposite approach — its core purpose is to generate a printable observation card from an image, then encourage you to put down your device and head outdoors.

This is a small local prototype submitted for Week 1 of the Hacktoberfest open-source AI challenge, themed "Touch Grass." It uses Python with scikit-learn's K-means clustering to extract dominant colors from an image, then pairs each color swatch with an observation prompt: notice a texture, contrast light and shadow, or sketch a small detail you might normally overlook. Take the card to a familiar outdoor spot and complete a brief observation — without disturbing plants or wildlife.

The author is upfront about limitations: this prototype was built with an AI coding agent and tested on October 11, 2026. It has not been field-tested with real users outdoors, and the demo uses an original geometric illustration rather than an actual photo taken on a walk. This kind of honest self-assessment is refreshingly rare in a landscape full of overhyped AI projects.

Technical Core: A Lightweight Approach with Three Clusters and 4,096-Pixel Sampling

The open-source heart of the project is its palette generation algorithm — scikit-learn's K-means, an unsupervised machine learning method. It fits up to three clusters on a sample of at most 4,096 RGB pixels to extract the dominant colors from an image.

It's worth emphasizing: there is no generative model here, and the observation prompts are entirely fixed text. The whole approach is deliberately simple — no large language model, no API keys, no accounts. Analysis runs entirely locally and never sends images to any external service. An internet connection is only needed to install dependencies on first setup; afterward, analysis runs offline and loads no serialized models.

The generated cards are also designed with privacy in mind: they contain no source image, filename, EXIF data, or location information. For a tool meant to be taken outside, these privacy-by-default choices are a sensible tradeoff.

K-means clustering is an unsupervised learning algorithm that partitions data points into K groups through iterative refinement: it starts by randomly initializing K "centroids," assigns each data point to its nearest centroid, recalculates the mean of each group as the new centroid, and repeats until centroids no longer move significantly. In the context of color extraction, each pixel is a three-dimensional data point (one component each for R, G, and B), and the centroid coordinates K-means finds correspond to the most visually representative colors in the image. Choosing K=3 means that no matter how complex the image, it gets distilled down to three dominant colors — reducing computational load while keeping generated cards clean and readable. The 4,096-pixel sampling cap is an empirical tradeoff between accuracy and speed: sufficient for extracting broad color tones while avoiding excessive processing time on high-resolution images. Euclidean distance in RGB space is K-means' default similarity metric, but it doesn't fully correspond to how human eyes perceive color differences (known as "perceptual uniformity") — a limitation the author explicitly acknowledges.

The Difference Between the Public Demo and Running Locally

The project provides an online demo card, but the author is clear: this is pre-computed output, not a real-time in-browser image analyzer.

To generate a card from a PNG or JPEG you have the rights to use, you need to run the Python tool locally:

python palette_walk.py --demo --out first-card

You'll need to set up the environment and install dependencies per the README first, then generate the HTML and use its print button to output the card. The author also notes honestly that neither browser printing nor actual field use has been tested.

Nearest neighbor interpolation is an image scaling method that maps each pixel in the target image directly to the nearest pixel in the source image, without any color blending. By contrast, bilinear or bicubic interpolation applies weighted averaging of surrounding pixels, introducing new intermediate color values at edges. For color extraction tasks, this "color mixing" introduces colors that don't exist in the source image, causing K-means to cluster incorrect dominant colors. This is exactly the problem Palette Walk encountered in its first test — geometric boundaries in the composite illustration produced blended colors during scaling. Switching to nearest neighbor sampling allowed the clustering results to accurately reflect the actual colors in the source image. This detail illustrates that even in a "lightweight prototype," seemingly minor engineering decisions in the underlying implementation can directly affect output quality.

Why Open Innovation Matters: Inspectable Tradeoffs

This project offers a concrete, small-scale answer to the question of what open source actually means. A local workflow makes all tradeoffs inspectable — anyone can modify the sampling method, number of clusters, or prompt text without depending on hosted models, API keys, or accounts.

The problems surfaced during development are instructive. The first test revealed that scaling at geometric boundaries in composite artwork blended colors; switching to nearest neighbor sampling preserved the source colors. A browser inspection uncovered misleading hue labels, which were corrected through regression checks. Five bounded tests now pass, covering known colors, source color preservation, card privacy, monochrome input, transparent input, byte limits, and color labels.

But the author doesn't shy away from the method's boundaries: these tests don't prove how the tool performs on real-world photos. RGB distance is not perceptually uniform, sampled palettes may miss fine details, and lighting changes affect color. The tool doesn't identify any objects or species, and it doesn't assess routes, weather, or outdoor safety.

Honest Self-Awareness Is This Small Project's Greatest Value

Palette Walk makes no claims about user numbers, revenue, or field outcomes. It repeatedly emphasizes that the next truly meaningful test is whether "someone actually finds these printed prompts helpful during a short walk."

In a context where AI projects typically chase scale and metrics, this deliberate smallness offers a useful reference point: an unsupervised clustering algorithm, fixed text prompts, and a locally privacy-first workflow are enough to constitute a focused, well-bounded, reproducible, and modifiable open-source prototype. It doesn't solve grand problems — but it explains clearly and honestly the small thing it does try to solve.

For developers looking to get started with K-means, or hoping to understand what it looks like to "responsibly describe an AI prototype," this repository is worth a look — not because of how powerful it is, but because of what it chose not to do.