Architecture decisions¶
This section records the significant decisions about IronLAB's design as a numbered chain of architecture decision records (ADRs). Each record states the context in which the decision was made, the decision itself, and its consequences, and links to the records it relates to. The discussion from which most of these decisions emerged is in the background section, and the resulting structure is summarised in the architecture reference.
Records that have been released on the main branch are never modified. A decision that changes is recorded in a new ADR that names the record it supersedes, and this index shows the earlier record as superseded.
| ADR | Decision | Status |
|---|---|---|
| 0001 | Figures are a retained IR with stable node identifiers whose Rust types are the source of truth; .fig files use Protocol Buffers, with JSON as a secondary format and both schemas generated. |
Accepted; its keying of data by DataId is superseded by 0022 |
| 0002 | The viewer is built with egui and eframe, using only Rerun-family user-interface crates plus rfd. |
Superseded by 0016, which keeps its choice for the desktop viewer; its tab strip is superseded by 0015 |
| 0003 | One scene compiler produces a display list that every backend draws; the canvas uses egui meshes now and custom wgpu pipelines with GPU picking later. | Accepted |
| 0004 | PDF is the first export format, written with krilla, with the page equal to the artwork, real subset text, and flat, painter-sorted shading. | Superseded by 0010 |
| 0005 | LaTeX mathematics is typeset in process with latex-rust from source stored in the IR, with a fallback and warning for unsupported input. | Superseded by 0017 |
| 0006 | Viewer interaction edits the IR, views reset from a snapshot, and linked axes form disjoint groups whose automatic limits are shared. | Superseded by 0008 |
| 0007 | The MVP excludes sockets, bindings, GPU picking and smooth shading, and offers an in-process viewer and a file viewer. | Accepted |
| 0008 | Figures change through typed, literal edits in atomic transactions, and the viewer shows the owner's source figure with the user's view changes as an overlay whose conflicts are detected by property path. | Accepted; its data edits are superseded by 0022 |
| 0009 | The scene compiler thins a series larger than its plot can resolve, keyed on the view, by largest-triangle-three-buckets for lines and by binning for markers, and every drawn point carries the index it has in the source data. | Accepted |
| 0010 | PDF export keeps the page equal to the artwork, real subset text and flat, painter-sorted shading, and draws an artist too dense for vector paths as an image rendered by the viewer's own renderer. | Accepted |
| 0011 | Images are three artist kinds (true-colour, colour-indexed and colour-mapped) placed by their pixel centres in a plane of the axes, drawn by every backend as one image item beneath one transform, with a policy per category for the pixels the colormap cannot colour. | Accepted; its treatment of an image on a logarithmic axis is superseded by 0021, and its colour-indexed and colour-mapped image kinds, its colormap and colour limits per axes, its lenient default for indices outside the colormap and its middle-colour legend samples by 0024 |
| 0012 | An artist whose data gives it nothing to draw is valid; validation and the scene compiler each warn of it, naming the artist, and export_pdf returns a report of what was left off the page. |
Accepted; its listing of ImageOnLogAxis among the warnings is superseded by 0021 |
| 0013 | Every path and image of a three-dimensional axes carries its depth and the viewer draws the axes with a depth buffer through pipelines of its own; the exporter writes the axes as vectors when a depth-tested and a painter's render prove the same picture and embeds the depth-tested render otherwise, reporting every raster and every unverified axes with its reason. | Accepted; its drawing of translucent faces with depth writes is superseded by 0021 |
| 0014 | The canvas produces one draw list per figure in figure points, which the viewer's own wgpu pipelines draw on screen and offscreen with the mapping as a uniform and clipping by scissor; the egui-mesh path is removed. | Accepted |
| 0015 | A figure is described only by the labels and parameters its author gives it; the viewer derives no facet of its own, ranks facets by how much of a collection they cover and how evenly they divide it, and counts each facet's values as though that facet were not filtered. | Accepted; its naming of figure labels is superseded by 0023, which calls them tags |
| 0016 | The figure engine is one crate, ironlab-canvas, built for WebAssembly in CI so that it can depend on no user interface; the egui viewer and an HTML <ironlab-figure> element are two hosts that draw only chrome over it, the browser host without egui, through a wgpu surface with the pipelines, multisampling and export of the native viewer, distributed as a bundle of static files. |
Accepted |
| 0017 | LaTeX mathematics is typeset in process with latex-rust, which applies TeX's conventions itself, so IronLAB neither rewrites the source nor resizes the glyphs; provenance records the typesetter's name and version separately. | Accepted |
| 0018 | A legend is either inside its axes or in a legend panel that occupies tiles of the layout and lists the entries of every axes that names it, merging entries whose display name and drawn sample both match; entries of either kind of legend are arranged in fixed or automatic columns, and the rows and columns of the tile layout have relative weights. | Accepted; its division of the tile layout by weight is superseded by 0019, its legend panel node by 0022, and its deferral of colourbars by 0024 |
| 0019 | An axis is reversed by a flag and keeps increasing limits, links share limits only, each axis has automatic, stepped or explicit ticks with automatic, hidden or explicit labels, the automatic locator guarantees a minimum number of ticks, and plot areas share the page by weight after the margins; lines and scatters may place a dimension relative to the plot area, and an axes may keep an equal or fixed aspect. | Accepted |
| 0020 | A legend lists either its automatic entries or an explicit list of items, in their order, each naming an artist or standing for no artist and optionally on a row of its own at its position in the list; a row or column of the tile layout is either weighted or fitted to the legend panels in it, and the scene warnings are available without an export. | Accepted |
| 0021 | An image whose plane has a logarithmic axis is a validation error whose message says how to draw the values as a surface; image and surface artists gain alpha data with the shape of their data and a scalar opacity, which multiply, with independent control of the faces and edges of a surface; contours gain an opacity for their isolines and one for their filled bands; and the translucent draws of a depth group are drawn after its opaque ones without depth writes. | Accepted |
| 0022 | Data arrays, axes and panels are nodes of the figure in one identifier space, created, removed and moved by the structural edits; a reference to a node of the wrong kind is an error and an unused data array a warning; a panel is one node kind that occupies cells and holds one content, a legend for now; and the kinds of node are declared once, from which their dispatch is generated. | Accepted |
| 0023 | A title is drawn as a heading, a label is drawn beside what it identifies, a name identifies a node to tools and is never drawn, and tags describe a figure to the browser; an artist's display name becomes its label and the figure's labels become tags. | Accepted |
| 0024 | A colour scale is a figure node that every colour-mapped artist names, with no scale on the axes and no inheritance; it is continuous, discrete, indexed or categorical, and its kind fixes both how values become colours and how it is drawn; the scale handles out-of-range and non-finite values for every artist, strictly by default for indices; one scalar image replaces the colour-indexed and colour-mapped images; and a scale is shown by a colourbar in a panel or inside an axes, or as an item of a legend. | Accepted |
| 0025 | One series artist replaces the line and the scatter, with optional size data and colour data per point or per segment; a line coloured per point is drawn as gradients between the colours of its points; and a line in a three-dimensional axes is drawn and depth-sorted segment by segment. | Accepted |
| 0026 | A bar artist draws the bars it describes, each at its position plus an offset in widths or along the axis, with its own width and a base from which its value is a length; grouping and stacking are facade helpers that write ordinary bar series; and individual bars are coloured through colour data and a colour scale of any kind, as the points of a series are. | Accepted |
| 0027 | A grid of cells that each hold one value is an artist of its own, rather than an extension of the surface or the scalar image. | Accepted |
| 0028 | Artists whose primary mark is a closed shape have a face and an edge; artists whose primary mark is a line that may shade an area have a line and a fill. | Accepted |
| 0029 | A histogram is binned when the figure is built and stores its binned values with a record of how the bins were made, so datatips report counts and densities without the sample. | Accepted |