Skip to main content

Bitmap

Bitmap visualizes 2D or 3D numeric arrays as images. It is useful for heatmaps, spectrograms, images, and any data that can be represented as a matrix (grayscale) or tensor (RGB).

You select Bitmap in SA Studio by choosing Bitmap from the visualization selector.

Internally this visualization is provided by showIntensity.

Supported data format​

Bitmap expects arrays, the shape of the array determines how it is interpreted:

  • shape: an array describing the dimensions:
    • [H, W] for a 2D grayscale image (height × width).
    • [H, W, 3] for a 3D RGB image (height × width × 3 color channels).

If a non-u8 type is used, grayscale images are normalized by scanning for min/max and scaling into the 0–255 range. For u8/U8, the 0–255 values are used as-is.

Basic usage​

A simple Bitmap shows a single grayscale array at its native size:

//plot: Bitmap
-- produce an sa_array-compatible record with shape [H, W]
select array [x..100,y..100] of f32 e where e = mod(x,2);

Or a single RGB array:

//plot: Bitmap
-- produce an sa_array-compatible record with shape [H, W, 3]
select Array[y..100,x..100,c..3] of U8 val
      where val = case when c = 1 then mod(x+y,256)
                       when c = 2 then mod(abs(x-y),256)
                       else mod((x + y)/2,256) end;

Each value is rasterized to an off-screen canvas and then drawn into the main visualization canvas.

Scaling and display size when using Multi plot​

Bitmap supports three size-related parameters:

  • scale_factor: numeric scale factor applied to the image (default 1).
  • display_width: target width in pixels (optional).
  • display_height: target height in pixels (optional).

These parameters can be set as visualization parameters (for example via Multi plot or directly from the environment) and control how the native array is scaled.

The rules are:

  • If display_width and display_height are both set and > 0:
    • Scale the image to exactly display_width × display_height.
  • Else if only display_width is > 0:
    • Scale width to display_width and adjust height proportionally.
  • Else if only display_height is > 0:
    • Scale height to display_height and adjust width proportionally.
  • Else if scale_factor is set and not 1:
    • Multiply both width and height by scale_factor (rounded to integers).
  • Else:
    • Use native size from shape.

Interpolation is disabled (imageSmoothingEnabled = false) to keep pixels sharp, which is particularly useful for heatmaps and spectrograms.

Examples​

Scale by factor:

//plot: Multi Plot
{"sa_plot": "Bitmap", "scale_factor": 3};
select Array[y..100,x..100,c..3] of U8 val
      where val = case when c = 1 then mod(x+y,256)
                       when c = 2 then mod(abs(x-y),256)
                       else mod((x + y)/2,256) end;

Fix width only (height derived from aspect ratio):

//plot: Multi Plot
{"sa_plot": "Bitmap", "display_width": 200};
select Array[y..100,x..100,c..3] of U8 val
      where val = case when c = 1 then mod(x+y,256)
                       when c = 2 then mod(abs(x-y),256)
                       else mod((x + y)/2,256) end;

Fix height only:

//plot: Multi Plot
{"sa_plot": "Bitmap", "display_height": 200};
select Array[y..100,x..100,c..3] of U8 val
      where val = case when c = 1 then mod(x+y,256)
                       when c = 2 then mod(abs(x-y),256)
                       else mod((x + y)/2,256) end;

Tiling modes​

Bitmap can tile multiple frames together into a single composite image. The tiling mode is controlled by the tile_mode parameter:

  • "o" (override / latest-only): show only the latest frame from the stream.
  • "h": horizontal tiling of all frames side by side.
  • "v": vertical tiling of all frames stacked on top of each other.
  • "MxN" (e.g., "2x2", "3x2"): grid tiling with M rows and N columns.

Frames are provided as arrays or nested arrays and are internally flattened into a simple list of array objects before tiling.

Latest-only mode (tile_mode: "o")​

This is the default. All incoming frames are buffered, but only the most recent one is shown.

//plot: Multi Plot
{"sa_plot": "Bitmap", "tile_mode": "o"};
[(select array [x..100,y..100] of f32 e where e = mod(x,2)),
(select array [x..100,y..100] of f32 e where e = mod(y,2)),
(select array [x..100,y..100] of f32 e where e = mod(x,2)),
(select array [x..100,y..100] of f32 e where e = mod(y,2))];

Horizontal tiling (tile_mode: "h")​

All frames are placed side by side. The total width is the sum of all frame widths; the height is the maximum of frame heights.

//plot: Multi Plot
{"sa_plot": "Bitmap", "tile_mode": "h"};
[(select array [x..100,y..100] of f32 e where e = mod(x,2)),
(select array [x..100,y..100] of f32 e where e = mod(y,2)),
(select array [x..100,y..100] of f32 e where e = mod(x,2)),
(select array [x..100,y..100] of f32 e where e = mod(y,2))];

Vertical tiling (tile_mode: "v")​

All frames are stacked vertically. The total height is the sum of all frame heights; the width is the maximum of frame widths.

//plot: Multi Plot
{"sa_plot": "Bitmap", "tile_mode": "v"};
[(select array [x..100,y..100] of f32 e where e = mod(x,2)),
(select array [x..100,y..100] of f32 e where e = mod(y,2)),
(select array [x..100,y..100] of f32 e where e = mod(x,2)),
(select array [x..100,y..100] of f32 e where e = mod(y,2))];

Grid tiling (tile_mode: "MxN")​

Frames are placed in a grid of M rows and N columns. Each cell in the grid is sized to the maximum width/height of the frames used.

Example: 2×2 grid of four frames:

//plot: Multi Plot
{"sa_plot": "Bitmap", "tile_mode": "2x2"};
[(select array [x..100,y..100] of f32 e where e = mod(x,2)),
(select array [x..100,y..100] of f32 e where e = mod(y,2)),
(select array [x..100,y..100] of f32 e where e = mod(x,2)),
(select array [x..100,y..100] of f32 e where e = mod(y,2))];

Only up to M*N frames are shown; extra frames are ignored.

//plot: Multi Plot
{"sa_plot": "Bitmap", "tile_mode": "2x3"};
[(select array [x..100,y..100] of f32 e where e = mod(x,2)),
(select array [x..100,y..100] of f32 e where e = mod(y,2)),
(select array [x..100,y..100] of f32 e where e = mod(x,2)),
(select array [x..100,y..100] of f32 e where e = mod(y,2))];

Grayscale vs RGB​

  • Grayscale (shape = [H, W]):

    • If the array is of type"u8", each value in array (0–255) is mapped directly to intensity.
    • For other numeric types, a min/max scan is performed and values are linearly scaled to 0–255.
    • Each pixel is drawn with R = G = B = value and full alpha (opaque).

  • RGB (shape = [H, W, 3]):

    • Each pixel uses the three consecutive values as red, green, and blue (alpha is set to 255).

Summary​

  • Bitmap visualizes 2D/3D array data (grayscale or RGB) as images.
  • Input must carry an array or a vector of arrays
  • Use scale_factor, display_width, and display_height to control output size.
  • Use tile_mode ("o", "h", "v", or "MxN") to combine multiple frames into a single composite image.
  • The visualization disables smoothing to preserve pixel details, making it well-suited for heatmaps, spectrograms, and similar intensity-based visualizations.