factoriax.analysis.build_progression

factoriax.analysis.build_progression#

Draw build snapshots as progression figures.

Both renderers take frames that the engine has already rendered, plus one integer for each map tile that says when a machine first landed there. Neither renderer runs the engine.

Two public renderers:

  • render_strip() draws an nrows x ncols grid of panels. Each panel shows the factory at one snapshot. One continuous outline traces the perimeter of the tiles added in that panel. There is no box around each tile.

  • render_heatmap() draws one panel of the final state. A dim layer covers the tiles that nothing was built on, and a continuous outline surrounds the built region. This shows the silhouette of what the run constructed.

Neither form owns a color. The highlight color, the dim color, and the dim opacity are all necessary arguments. This module draws the shapes, and the caller decides how they look.

factoriax.analysis.build_progression.render_heatmap(final_frame: ndarray, placement_phase: ndarray, tile_px: int, out_path: Path | str, *, highlight_color: str, dim_color: str, dim_alpha: float, outline_linewidth: float = 3.5) → Path#

Render the inverted build-heatmap (Form D).

A tile that nothing was built on gets a translucent overlay, so the eye passes over it. The built region keeps its full-color render and gets a continuous outline in highlight_color.

The three groups of tiles are not a partition. The overlay covers phase -1, and the outline covers phases 1 and higher. A phase-0 tile therefore gets neither: it stays at full color with no outline, because it is spawn furniture and not something the run built.

Parameters:

  • final_frame – The final snapshot as uint8 of shape (H_px, W_px, 3).

  • placement_phase – Integer array of shape (H, W) in tiles, as in render_strip().

  • tile_px – The width of one map tile in pixels.

  • out_path – Where to write the image. The extension sets the format. Missing parent directories are created.

  • highlight_color – The outline color for the built region.

  • dim_color – The fill color of the overlay on the tiles that were never built on.

  • dim_alpha – The opacity of that overlay, from 0.0 to 1.0.

  • outline_linewidth – The matplotlib line width of the outline.

Returns:

out_path as a Path, after the write.

Return type:

pathlib.Path

Notes

The function writes a file and closes its own figure.

factoriax.analysis.build_progression.render_strip(frames: ndarray, placement_phase: ndarray, snapshot_labels: Sequence[str], tile_px: int, out_path: Path | str, *, highlight_color: str, dim_color: str, dim_alpha: float, nrows: int = 2, ncols: int = 3, outline_linewidth: float = 3.0) → Path#

Render the build-progression strip (Form C).

Panel k shows snapshot k. Every panel after the first dims the tiles outside the region built so far, and outlines the tiles added in that panel. Panel 0 is the spawn state. It gets an outline but no dim overlay, because nothing is built yet.

The built region covers phases 1 and higher. A phase-0 tile therefore counts as spawn furniture, not as something the run built, and panels after the first dim it. render_heatmap() draws the same distinction.

Parameters:

  • frames – Snapshots as uint8 of shape (N, H_px, W_px, 3), one for each panel. N sets the number of panels.

  • placement_phase – Integer array of shape (H, W) in tiles, indexed as placement_phase[y, x]. The value is the index of the snapshot that first placed a machine on that tile. A tile with no machine holds -1.

  • snapshot_labels – The title of each panel. It must hold at least N entries.

  • tile_px – The width of one map tile in pixels. Tiles are square, and frames must be tile_px times larger than placement_phase on both axes.

  • out_path – Where to write the image. The extension sets the format, and matplotlib accepts PNG and SVG among others. Missing parent directories are created.

  • highlight_color – The outline color for the tiles added in the current panel.

  • dim_color – The fill color of the overlay on the tiles outside the built region.

  • dim_alpha – The opacity of that overlay, from 0.0 to 1.0.

  • nrows – Rows in the panel grid.

  • ncols – Columns in the panel grid.

  • outline_linewidth – The matplotlib line width of the outline.

Returns:

out_path as a Path, after the write.

Return type:

pathlib.Path

Raises:

ValueError – When nrows * ncols is less than the number of panels. The check runs before the figure exists, so a failed call leaves nothing open and writes no file.

Notes

The function writes a file and closes its own figure. Cells of the grid beyond the last panel are hidden, not left blank.