How a 45,225-pixel painting became a blurry thumbnail

takhir adilzhanov — Tue, 08 Sep 2026 11:30:10 +0000

I am building Polotno, a free, noncommercial gallery where a visitor can zoom into a painting, read its story, or listen to a prepared audio guide. The collection currently contains 509 works, 295 artists, and 20 tours.

One painting exposed a mistake in my image pipeline better than any synthetic performance test could.

Mi Youren’s Cloudy Mountains is a horizontal handscroll. The source used by the gallery is 45,225 × 4,878 pixels—roughly 221 million pixels. The source was detailed enough for deep zoom, yet the painting looked blurred in the catalog.

The problem was not JPEG quality. I had resized and cropped in the wrong order.

One image could not serve two different jobs

The full painting view and the catalog card look like two versions of the same component, but they ask the image pipeline for different things.

In the viewer, a person first sees the complete work and then zooms into a small area. Sending the full 45,225-pixel-wide image for the initial view would waste bandwidth and ask the browser to decode far more pixels than it needs.

The catalog has the opposite constraint. It shows many paintings at once, each inside a card with a relatively compact aspect ratio. It needs a recognisable crop, several responsive sizes, and no deep-zoom machinery.

Treating both surfaces as one image-delivery problem produced a poor result in the catalog.

Deep Zoom sends only the required region and resolution

The painting viewer uses OpenSeadragon and Deep Zoom pyramids. A pyramid contains the image at several resolution levels. Each level is split into tiles.

At the overview scale, the browser requests a low-resolution level. After a visitor zooms in, it requests detailed tiles only for the visible area. The interaction resembles a map: the whole world is not downloaded at street-level resolution before the first frame appears.

In Polotno, the viewer currently limits concurrent image requests to six and caps its image cache at 20 entries on small screens or in TV mode, and 36 on larger screens. Those numbers are operational limits, not universal recommendations; they still need measurement on real devices and networks.

Deep Zoom adds costs of its own. I have to prepare and store many files, the browser makes more HTTP requests, and the delivery path has to cache immutable tiles correctly. For a gallery whose main interaction is close looking, that trade-off is useful. For a grid of cards, it is unnecessary.

The 640-pixel thumbnail had only 69 pixels of height

The original catalog pipeline generated a conventional thumbnail of the whole scroll. At 640 pixels wide, the proportional height was approximately 69 pixels.

The CSS card was much taller. object-fit: cover filled the card by enlarging the tiny thumbnail and cutting off both sides. The screen therefore showed a stretched fragment of a 69-pixel-high image.

Increasing the encoder quality could not restore detail that had already disappeared. A bigger source file was available, but the pipeline had reduced it before deciding which part the card needed.

The useful order is:

Choose the region that represents the work in the card.
Extract that region from a detailed source.
Resize the crop to the delivery sizes.
Encode immutable card assets.

For local paintings, the preparation script reconstructs the crop from source tiles. For some museum-hosted images, it requests the required region through IIIF. It does not generate or extend the painting with an image model.

The crop logic begins with a default viewing region and constrains its aspect ratio before reading pixels:

w, h = artwork["width"], artwork["height"]
bounds = artwork.get(
    "defaultViewBounds",
    {"x": 0, "y": 0, "width": 1, "height": 1},
)

x = bounds["x"] * w
y = bounds["y"] * h
crop_w = bounds["width"] * w
crop_h = bounds["height"] * h

ratio = max(0.7, min(1.5, crop_w / crop_h))

The production script then reads the required tiles, assembles the crop, and generates WebP variants up to 480, 960, and 1,440 pixels wide. It never enlarges a source merely to satisfy a target width.

The old 640-pixel-wide thumbnail preserved the whole scroll but had only 69 vertical pixels.

The new asset crops first and resizes second. The complete work remains unchanged in the viewer.

`srcset` selects among prepared card assets

Once the assets exist, the React component exposes them with width descriptors:

const candidates = variants.map(
  variant => `${variant.src} ${variant.width}w`,
)

return (
  <img
    src={variants.at(-1)?.src ?? src}
    srcSet={candidates.join(", ")}
    sizes="(max-width: 700px) 100vw, (max-width: 1200px) 50vw, 33vw"
    loading={eager ? "eager" : "lazy"}
    decoding="async"
    alt={alt}
  />
)

The browser chooses a candidate using the rendered size and device pixel ratio. Images below the first screen load lazily. The original overview remains a fallback if a prepared asset fails.

This change produced dedicated card variants for all 509 works. Together they occupy about 263 MB in storage. A visitor does not download that set at once, but a detailed card can still increase the traffic for a particular screen. Storage size, transfer size, and decoded memory are different budgets; reporting only one of them hides part of the cost.

Text and audio need separate delivery decisions

The same distinction between library size and per-visit cost appears outside the image pipeline.

The complete artwork database with long-form stories is about 7.6 MB of JSON. The initial catalog uses a separate summary file of about 717 KB, or 155 KB in a local gzip measurement. A full story is fetched only when its painting opens. The client keeps at most eight loaded stories in memory for quick return navigation.

The audio guide is also prepared before a visitor arrives. The Russian and English tracks are ordinary MP3 files generated from the reviewed text. Playback does not call a model at runtime. The current inventory contains 8,228 recordings—about 55 hours of audio—so the relevant problems are storage, byte-range delivery, invalidation, and caching.

Each recording identifier depends on the exact text, voice, model, and delivery instruction. When one paragraph changes, the build replaces only the related files.

A fast local build does not prove fast delivery

The public domain currently passes through one Nginx proxy before it reaches the application. I added that route after direct access to the hosting provider failed on a tested Russian network. It solved that access problem, but it also made one server and its connection part of every request path.

Caching can reduce requests to storage. It cannot create bandwidth that the proxy does not have. I therefore do not treat a good desktop run or one Lighthouse score as proof that the gallery is ready for a large simultaneous audience.

The next useful measurements are complete user flows on constrained mobile connections: opening the catalog, selecting a painting, zooming into several areas, and starting audio. I also need cache-hit data from the proxy and a load test before changing the delivery architecture.

The bug was a mismatch of intent, not resolution

The 45,225-pixel source looked blurred because the pipeline answered the wrong question. It created a small picture of the entire scroll, while the card needed a detailed crop of one region.

Separating viewer assets from catalog assets made the responsibilities clearer:

tiled pyramids support exploration;
prepared crops support recognition in a grid;
srcset handles responsive delivery;
per-item JSON and MP3 files keep the first visit independent of the total library size.

You can inspect the result in Polotno. Registration is not required. If one of the paintings loads slowly, I would especially value the work you opened, your device, and your network conditions—those details are more useful than a generi

DEV Community: takhir adilzhanov