Sign inRegisterCheck connection

Weather Avatar Reference: Required Fields, Size, and Cache Headers

Reference card for PHP-GD weather avatars: required observation fields, image size, and HTTP cache headers that keep a small identity image honest.

Back to Cumulus weather software guides

A weather avatar is a small identity image: a square (or near-square) PNG that a forum, sidebar, or comment header can hot-link so a station is recognizable at a glance. Because the canvas is tiny, the documentation has to be stricter than the artwork. This page is the reference card for that contract: which fields must appear, what size to declare, and which HTTP cache headers keep the glyph from becoming yesterday’s weather. How to pack information into few pixels is /projects/phpgdavatar. This URL does not repeat that design essay.

PHP GD (the gd extension) is the historical renderer. This card does not redistribute scripts.

Historical context

Cumulus community sites published current values as realtime.txt and then asked PHP on the web host to draw images for places that would not embed a full dashboard: forum profiles, webring buttons, signature strips. The avatar was the square member of that family. The banner (/projects.reference.phpgdbanner) was the wide member. Both read a current packet. Both failed in public the same way: missing units, missing time, and caches that treated a dynamic PNG like a static logo.

The historical TNET reference cluster recorded those constraints so an operator could configure a generator without reading the PHP. The reference hub lists the five card fields this page fills for avatars.

Required fields: an identity image is still an observation product

An avatar that shows “72” without a unit, a time, or a station name is decoration. WMO observing practice treats quantity, unit, time, and instrument identity as part of the measurement. A 88-pixel square cannot print a METAR. It can still refuse to omit the contract.

Minimum visible set

  1. Station identity — a short name or ID. Without it, the number is anonymous and unsafe to quote.
  2. Air temperature and a unit token — C or F (Cumulus realtime.txt field 15 in the classic map is the temperature unit without the degree glyph). Do not assume Fahrenheit because the operator is in the United States.
  3. A time, or a freshness mark that maps to a documented timeout — a clock printed at 8-point type, or a visible “stale” state when the packet is older than T. An avatar that never looks stale is claiming to be live while being a sticker.
  4. The unit system actually in the file — copy the token from the packet; do not hard-code F in GD text if field 15 says C.

Optional, only if labeled

  • Humidity, wind, rain today: useful, easy to misread without a period (“today” needs a reset rule).
  • Wind chill, heat index, humidex, apparent temperature, feels-like: derived. If they appear, they must not share the unlabeled slot that temperature uses. MX added feels-like as a later realtime.txt field; a card that lists “the temperature field” without a version is incomplete.
  • Forecast or Zambretti-style numbers: scenario, not observed. They do not belong in the same glyph cell as the thermometer.

Inputs the generator must document even if they are not drawn

  • Source file and flavour (legacy Cumulus 1 vs MX; not ClientRaw unless the avatar is a Weather Display build).
  • Field indexes it reads, with a citation date to the Cumulus Wiki map.
  • Behavior when GD or a TTF font is missing: fail with a labeled error image, not a blank 200 OK.

Do not paste the vendor’s full field table into this card. Cite it.

Image size: declare geometry as a specification

Forum software of that era commonly constrained avatars to a square budget: 80×80, 88×88, 100×100, or 120×120 pixels were typical classes, not a TNET-specific recovered measurement. The scientific requirement is to state the pixel size the generator emits, the MIME type (image/png or image/gif if that is what you actually send), and whether the image is resized by the forum (which blurs unit glyphs).

Document:

  • Canvas width × height in pixels, not “small.”
  • Colour type — palette PNG versus truecolour; palette is smaller and was common for GD buttons.
  • Safe text region — a rectangle inside the canvas where the temperature string must fit at the documented font size. If the number can clip to “10” instead of “100,” the size spec is wrong.
  • Hot-link expected context — profile thumbnail versus standalone URL. Thumbnails that downscale 120×120 to 48×48 will destroy a four-field layout; the card should say the avatar is designed for 1:1 display.

A size that changes with the temperature string (wider for “−14.5”) is a different product. Record it. Banners are allowed to be wide; avatars that secretly become banners break every forum layout that reserved a square.

Cache headers: freshness is part of the image

A PNG URL that never expires will show noon on a night page. PHP that sends no cache headers often gets heuristic caching anyway. RFC 9111 defines how Cache-Control max-age marks a response stale after a number of seconds, and how unqualified no-cache forbids reuse without validation.

For a weather avatar, the reference should name a policy that matches the upload interval, not a CDN default.

| Header | What the card should specify | |---|---| | Content-Type | image/png (or the type you really emit) | | Cache-Control | max-age on the order of the realtime interval, or no-cache plus validators if you require revalidation every fetch | | ETag or Last-Modified | A validator derived from packet time or from a hash of the drawn values, so a 304 can be returned when weather has not changed | | Expires | Only if consistent with max-age; do not send a date years in the future |

What not to do. Cache-Control: public, max-age=31536000 is correct for a versioned static logo. It is incorrect for a URL whose meaning is “current temperature.” no-store prevents reuse; it also prevents 304s and will hammer GD on every forum page load. no-cache still allows storing the response but requires validation (RFC 9111, §5.2.2.4). That is often the honest middle for a live glyph: store, revalidate, redraw only when the packet changed.

Tie the avatar’s max-age to the same T used in the stale-upload checker card. If the checker says the file is stale after 300 seconds and the avatar is cacheable for 86400 seconds, the public identity of the station is defined by the CDN, not by the logger.

Document whether shared caches (proxies) may store the image (public vs private). A personalized avatar is rare; a station-wide avatar is usually public with a short freshness lifetime.

Practical checklist

  1. List required on-canvas fields: identity, temperature, unit, freshness.
  2. Label derived and scenario values if they appear.
  3. State width × height, MIME type, and 1:1 display assumption.
  4. Cite source file, flavour, and field map date.
  5. Specify Cache-Control and validators; match max-age to the upload interval.
  6. Define the error image when GD, fonts, or the packet are missing.
  7. Record license as found in the PHP header; do not attach a ZIP.
  8. Leave information-density design to /projects/phpgdavatar.

Modern relevance

Forums moved. Hot-linked squares remain: Discord, Mastodon, status badges, Open Graph fallbacks. The card still applies. JSON APIs did not remove the need for a pixel-size declaration or a cache lifetime that matches the observation cadence. A badge that caches for a week is a climate sticker.

TNET research bridge

Provenance, units, and freshness of public weather records are the same issues TNET states on data sources, quality controls, and methodology. That page does not specify avatar geometry. The Cumulus hub indexes the project family. How the service works is the place to take a labeled observed-versus-derived distinction into the current product.

Sources