Skip to content

Visualisation Styling Alignment

src.visualisation intentionally mirrors the plotting style used in the quartz/com and topaz/rl-skeleton visualisation packages.

What is mirrored

  • palette aliases for the main algorithms
  • paper-style matplotlib rcParams
  • panel background, grid, and spine colors
  • zero-length ticks and scientific step-axis formatting
  • shared top legend and figure save padding
  • shared header layout now measures the rendered legend height before calling tight_layout, so wrapped two-row legends do not overlap subplot titles
  • moderate paper-scale font sizing, lighter default line strokes, tight title/label padding, and capped major x-axis ticks so scaled-down exports stay readable
  • PDF and PostScript output embeds TrueType fonts, and axes rasterize artists below z-order 1.9 so background bands and event markers stay compact while the learning curves remain vector graphics
  • translucent shared-legend handles are composited against the figure background before export, avoiding unstable transparency in vector viewers
  • paper_panel=True plot flags use a local use_paper_panel_style() preset for figures that will be embedded as small paper panels. The preset keeps the existing canvas sizes and filenames, but increases relative axis labels, tick labels, offset text, grid/spine widths, and line strokes. Project-specific export code should choose alternate filenames such as *_paper.png when it wants separate paper assets.

Why this stays local

omsh keeps a local copy of the styling helpers instead of importing from the sibling rl-engine checkout at runtime.

This keeps notebook usage self-contained, avoids a cross-repo path dependency, and lets omsh preserve its local plotting behavior such as world-model boundary markers, shield-level overlays, and shield telemetry-specific layouts.

Expected maintenance flow

When the shared graph styling changes in a meaningful way, update src/visualisation/styling.py and the small presentation helpers in src/visualisation/common.py to match the quartz/com and topaz/rl-skeleton reference implementations.

Behavioral plotting logic in omsh does not need to match those repositories unless we explicitly decide to consolidate the plotting packages more broadly.

Module Placement

The plotting package lives under src/ rather than notebooks/ because the helpers are imported by both marimo notebooks and normal Python test modules.

Keeping the package under src.visualisation makes that shared usage explicit and avoids treating notebook plotting helpers as notebook-only code.