Core Concepts
The few ideas the whole library rests on: what holds the data, what draws it, why resolution is not the cost, and what actually is.
Sources and canvases
A source holds what to draw. A Canvas decides how it looks and where it goes. Keeping the two apart means one field can be drawn by different canvases, and one Canvas can be restyled without touching the data.
| Source | Holds | Use it for |
|---|---|---|
ValueField | A fixed grid of numbers | Heatmaps and any picture coloured by magnitude. |
PaletteField | A fixed grid of exact palette indices | Images, 3D frames, and discrete states. |
ValueScroll | A rolling window of number columns | Heatmaps that gain one column per bar. |
PaletteScroll | A rolling window of palette-index columns | State strips and scrolling pictures. |
| Shape queue | Rectangles, triangles, ellipses, polygons | Profiles, zones, and interfaces that do not sit on a grid. |
The shape queue lives on the Canvas itself. See Filled Shapes.
Cells are not drawings
Pine Script allows 500 boxes and 100 polylines per script. A picture drawn as one box per cell is finished at 20 × 25 cells. PineCanvas breaks that one-cell, one-drawing relationship:
- It traces each same-colour region as an outline and discards the edges inside it.
- It joins the separate regions of one colour through zero-width links, which enclose no area and draw nothing.
- It packs the result into polylines of up to 10,000 points each.
A solid block of thousands of cells costs four corners. What a picture costs is the length of its boundaries, not the number of its cells.
Colour levels and regions
Every cell ends up at one colour level. A palette field supplies the level directly. A value field is quantized into the number of levels set with colorLevels(), from 2 to 100.
- Fewer levels make larger regions, which need fewer points.
- Each visible level needs at least one polyline, so a picture can show at most 100 colours.
- Noisy data fragments regions. Smoothing it, or lowering the level count, reduces geometry more than lowering the resolution does.
After a field render, componentCount() reports how many same-colour regions were found and drawingCount() how many polylines they took.
Transparency
A transparent cell produces no geometry. In a value field the transparent value is na. In a palette field it is the index -1. Both constructors start every cell transparent.
na for the faintest values of a heatmap removes the largest and least informative region of the picture, and the chart shows through instead.Two renderers, chosen for you
A source of up to 100,000 cells is drawn by the flat renderer. A larger one moves to the large renderer, which works through the picture in tiles and keeps its data in storage bands, so it stays inside Pine's collection limits. The switch is automatic and nothing in the calling script changes.
A Canvas owns its drawings
Each Canvas keeps the polylines it created. Every field draw and every drawShapes() call replaces that Canvas's previous frame. Two things that must be visible together therefore need two canvases. Layers & Drawing Budgets shows how they share the polyline limit.
Caching
PineCanvas reuses cached contour work between frames. When the source, the style, and the placement are all unchanged, a draw call skips replacing the drawings altogether. Redrawing on every tick of a realtime bar is cheap when nothing changed, and costs a full render when something did.
Coordinates
- Horizontally a field is placed by bar index or by timestamp. Bar-index placement reaches 10,000 bars back and 500 bars forward. Time placement has no such bound.
- Vertically a field spans from
bottomtotop. On the price chart those are prices. In a separate pane they are any numbers you choose. - Shapes always use chart time and price, through
chart.point.from_time().