Visualization#

ElectroSim provides rich real-time visualization. This page describes the available visualization modes and customization options.

Particle Rendering#

Color Coding#

Particles are color-coded by charge:

  • Red: Positive charge (q > 0)

  • Blue: Negative charge (q < 0)

  • White: Neutral (|q| < 10⁻¹² C, effectively zero)

Colors are defined in electrosim/config.py:

  • COLOR_POSITIVE: RGB for positive particles (default: red)

  • COLOR_NEGATIVE: RGB for negative particles (default: blue)

  • COLOR_NEUTRAL: RGB for neutral particles (default: white)

Particle Glow Effect#

Particles can display a soft glow that scales with charge magnitude. Toggle with B key.

Configuration (electrosim/config.py):

  • GLOW_ENABLED: Enable/disable glow (default: True)

  • GLOW_ALPHA_AT_MAX: Alpha value when |q| = MAX_CHARGE_C (default: 255)

  • GLOW_RADIUS_SCALE: Glow radius multiplier (default: 100.0)

The glow uses cached surfaces for performance. Cache settings:

  • GLOW_CACHE_INTENSITY_STEPS: Quantization steps for intensity

  • GLOW_CACHE_MAX_SURFACES: Maximum cached glow surfaces

Particle Borders#

  • White border: Selected particle

  • Gold border: Fixed (immobile) particle

  • Both borders can appear simultaneously for a selected fixed particle

Border colors in config:

  • COLOR_SELECTED_BORDER: Selection highlight (white)

  • COLOR_FIXED_BORDER: Fixed particle indicator (gold)

Electric Field Visualization#

Press E to toggle electric field visualization. The field is sampled on a grid and rendered as vector arrows.

Display Modes#

Press M to cycle between two field visualization modes:

Brightness Mode#

  • Arrow length: Fixed (FIELD_FIXED_ARROW_LENGTH_PX, default: 16 px)

  • Arrow opacity/brightness: Varies with field magnitude |E|

  • Color blending: Arrows blend toward white at high field strength

  • Best for: Showing field structure without clutter

Scaling parameter:

  • FIELD_BRIGHTNESS_SCALE: Multiplier for brightness mapping (default: 2.0)

Length Mode#

  • Arrow length: Proportional to |E|, clamped to max

  • Arrow opacity: Constant

  • Best for: Direct magnitude comparison

Scaling parameters:

  • FIELD_VECTOR_SCALE: Conversion from field strength to pixels (default: 2e-3)

  • FIELD_VECTOR_MAX_LENGTH_PX: Maximum arrow length (default: 50.0 px)

Field Grid Configuration#

  • FIELD_GRID_STEP_PX: Spacing between field sample points (default: 30 px)

    • Smaller values: Higher resolution, more computation

    • Larger values: Coarser grid, faster rendering

  • FIELD_ALPHA_MIN_DRAW: Minimum alpha to draw (default: 2, suppresses very weak fields)

Field Sampler#

For performance with many particles, enable the field sampler:

  • FIELD_SAMPLER_ENABLED: Cache field grid per frame (default: True)

When enabled, the entire field grid is computed once per frame and reused for rendering. Disable if you prefer on-demand field evaluation.

Implementation: electrosim.rendering.field_sampler.ElectricFieldSampler

Force Vectors#

Press F to show force vectors on each particle.

  • Color: Yellow (configurable via COLOR_FORCE_VECTOR)

  • Length: Proportional to force magnitude

  • Scaling: FORCE_VECTOR_SCALE (default: 100.0 px per Newton)

  • Max length: VECTOR_MAX_LENGTH_PX (default: 80.0 px)

Force vectors originate at the particle center and point in the direction of net electromagnetic force.

Velocity Vectors#

Press V to show velocity vectors on each particle.

  • Color: Green (configurable via COLOR_VELOCITY_VECTOR)

  • Length: Proportional to speed

  • Scaling: VELOCITY_VECTOR_SCALE (default: 10.0 px per m/s)

  • Max length: VECTOR_MAX_LENGTH_PX (default: 80.0 px)

Velocity vectors originate at the particle center and point in the direction of motion.

Particle Trajectories#

Press T to toggle trajectory trails.

Trail Appearance#

Trails are polylines that fade from recent to old positions:

  • Color:

    • Positive particles: COLOR_TRAIL_POS (light red)

    • Negative particles: COLOR_TRAIL_NEG (light blue)

  • Width: TRAIL_WIDTH_PX (default: 3 px)

  • Alpha: Fades from TRAIL_ALPHA_MAX to TRAIL_MIN_ALPHA over time

  • Duration: TRAJECTORY_HISTORY_SECONDS (default: 3.0 s)

Trail Configuration#

Parameters in electrosim/config.py:

  • TRAIL_WIDTH_PX: Line thickness

  • TRAIL_ALPHA_MAX: Maximum opacity for newest trail segment (default: 235)

  • TRAIL_MIN_ALPHA: Minimum opacity for oldest visible segment (default: 5)

  • TRAIL_FADE_SECONDS: Fade duration (default: same as history duration)

  • TRAIL_AA_EDGE_EXTEND_PX: Anti-aliasing edge width (default: 1 px)

  • TRAIL_AA_EDGE_OPACITY_FACTOR: Edge opacity multiplier (default: 0.35)

Trails use a dedicated surface with alpha blending for smooth fading.

Implementation: electrosim.rendering.trails

Metric Grid#

Press G to toggle the metric grid overlay.

Shows world-space coordinates in meters:

  • Minor lines: Every GRID_METER_STEP meters (default: 1.0 m)

  • Major lines: Every GRID_MAJOR_EVERY steps (default: 1)

  • Colors:

    • Minor: COLOR_GRID (dark gray)

    • Major: COLOR_GRID_MAJOR (lighter gray)

  • Line widths:

    • Minor: GRID_LINE_WIDTH (default: 1 px)

    • Major: GRID_MAJOR_LINE_WIDTH (default: 2 px)

The grid helps visualize particle positions and distances in physical units.

Overlay Information#

The top-left overlay displays real-time statistics:

  • FPS: Current frame rate

  • N: Number of particles

  • Speed: Simulation speed multiplier (0.5×, 1×, 2×, 4×)

  • dt: Integration timestep (seconds)

  • Substeps: RK4 substeps per frame

  • E_kin: Total kinetic energy (Joules)

  • E_pot: Total potential energy (Joules)

  • E_tot: Total energy (Joules)

Performance Profiling#

Enable detailed per-frame timing with PROFILE_OVERLAY_ENABLED = True:

Additional overlay metrics:

  • Physics: Time spent computing forces and integration (ms)

  • Field: Time spent computing/rendering electric field (ms)

  • Render: Time spent drawing particles, trails, vectors (ms)

  • Total: Total frame time (ms)

Overlay configuration:

  • OVERLAY_TEXT_COLOR: Text color (default: light gray)

  • OVERLAY_SHADOW_COLOR: Shadow color (default: black)

  • OVERLAY_SHADOW_OFFSET: Shadow offset in pixels (default: (1, 1))

Implementation: electrosim.rendering.overlay

Background and Theme#

Background color is configurable:

  • COLOR_BG: Background RGB (default: dark gray, (18, 18, 22))

ElectroSim uses a dark theme by default for better contrast with bright particles and field vectors.

Performance Considerations#

Visualization can be the performance bottleneck for large numbers of particles:

  1. Electric field: Most expensive, especially with many particles

    • Reduce FIELD_GRID_STEP_PX for fewer sample points

    • Enable FIELD_SAMPLER_ENABLED for caching

    • Use brightness mode instead of length mode

  2. Particle glow: Moderate cost due to alpha blending

    • Disable with GLOW_ENABLED = False or press B

    • Reduce GLOW_RADIUS_SCALE for smaller glows

  3. Trajectories: Moderate cost, scales with history length

    • Reduce TRAJECTORY_HISTORY_SECONDS for shorter trails

    • Disable with T key

  4. Vectors: Low cost unless many particles

    • Disable force/velocity vectors (F, V) if not needed