Plot Helper Utility

Interactive 2D graph/plot widget for ImGui - supports multi-series data, Catmull-Rom spline interpolation, auto-scaling, dragging, zooming, annotations, and tooltip hover.

Class: `C` (returned by factory function)

Method	Signature	Description
`C:init(params)`	`params: {scale, autoScale, showCatmullRomCurve, catmullDataPoints, allowZoom}`	Initialises the plot with scale/options
`C:setData(data)`	`data: {{x, y, ...}, ...}`	Sets graph data (multiple Y per X supported)
`C:setDataMulti(data)`	`data: {{{x,y}, ...}, ...}`	Sets multi-series data directly
`C:setSeriesNames(names)`	`names: {string, ...}`	Sets display names per series
`C:setSeriesColors(colors)`	`colors: {{r,g,b,a}, ...}`	Sets colours per series (0–1 range)
`C:setSeriesFormat(format)`	`format: {{name, color, uColor}, ...}`	Sets combined series format
`C:setAnnotationX(annotation)`	`annotation: {{x, label}, ...}`	Adds vertical annotation lines at X values
`C:setScale(xMin, xMax, yMin, yMax)`	All optional	Sets graph domain/range (nil = keep current)
`C:scaleToFitData()`	-	Auto-fits scale to include all data points with 10% margin
`C:draw(width, height, dt)`	-	Main render call; draws grid, data points, splines, crosshair
`C:overlayTextLines(lines)`	`lines: {string, ...}`	Overlays text lines on the graph
`C:generateCatmullSplinePoints()`	-	Pre-computes Catmull-Rom interpolation curves
`C:graphPtToImSS(x, y, clamp)`	-	Converts graph coords to ImGui screen-space
`C:graphPtToImWS(x, y)`	-	Converts graph coords to ImGui window-space

Usage Example

local plotHelper = require('/lua/ge/extensions/editor/util/plotHelperUtil')

-- Create a plot instance
local plot = plotHelper({
  scale = {xMin = 0, xMax = 100, yMin = 0, yMax = 200},
  autoScale = true,
  showCatmullRomCurve = true,
  catmullromCurveLines = 20,
  allowZoom = true,
  pointSize = 4,
  pointThickness = 2,
  formatX = "%0.1f",
  formatY = "%0.1f"
})

-- Set multi-series data: torque and power curves
local torqueData = {{1000, 80}, {2000, 140}, {3000, 180}, {4000, 200}, {5000, 190}}
local powerData = {{1000, 12}, {2000, 42}, {3000, 81}, {4000, 120}, {5000, 142}}

plot:setDataMulti({torqueData, powerData})
plot:setSeriesNames({"Torque (Nm)", "Power (kW)"})
plot:setSeriesColors({{1, 0.3, 0, 1}, {0, 0.6, 1, 1}})

-- Add annotation at peak torque
plot:setAnnotationX({{4000, "Peak Torque"}})

-- Draw in an ImGui window each frame
local dt = imgui.GetIO().DeltaTime
plot:draw(400, 300, dt)

-- Overlay stats
plot:overlayTextLines({"Peak: 200 Nm @ 4000 RPM"})

-- Interactive controls (built-in):
-- * Left-click drag to pan
-- * Mouse scroll to zoom
-- * Double-click to reset (via external logic)
-- * Hover data points for tooltips
-- * Crosshair follows cursor

Additional Internal Methods

Method	Description
`C:moveGraph(dt)`	Handles mouse-drag panning
`C:zoomGraph(dt)`	Handles scroll-wheel zoom based on mouse position
`C:drawCatmullSpline()`	Renders pre-computed Catmull-Rom curves
`C:drawGridAndAxesLabels()`	Draws grid lines, border, and axis tick labels
`C:getOptimalTickIncrement(ticks, range)`	Computes best tick spacing (1/2/5 increments)
`C:drawData()`	Renders data points as circles with hover tooltips
`C:normToImSS(x, y)`	Normalized (0–1) → ImGui screen-space coords
`C:normToImWS(x, y)`	Normalized (0–1) → ImGui window-space coords
`C:roundToDigits(num, dec)`	Rounds number to specified decimal places
`C:getOrderOfMagnitude(num)`	Returns floor of log10(abs(num))
`C:scaleX(x)`	Maps normalized X to graph X value
`C:scaleY(y)`	Maps normalized Y to graph Y value

Class: `C` (returned by factory function)

Method	Signature	Description
`C:init(params)`	`params: {scale, autoScale, showCatmullRomCurve, catmullDataPoints, allowZoom}`	Initialises the plot with scale/options
`C:setData(data)`	`data: {{x, y, ...}, ...}`	Sets graph data (multiple Y per X supported)
`C:setDataMulti(data)`	`data: {{{x,y}, ...}, ...}`	Sets multi-series data directly
`C:setSeriesNames(names)`	`names: {string, ...}`	Sets display names per series
`C:setSeriesColors(colors)`	`colors: {{r,g,b,a}, ...}`	Sets colours per series (0–1 range)
`C:setSeriesFormat(format)`	`format: {{name, color, uColor}, ...}`	Sets combined series format
`C:setAnnotationX(annotation)`	`annotation: {{x, label}, ...}`	Adds vertical annotation lines at X values
`C:setScale(xMin, xMax, yMin, yMax)`	All optional	Sets graph domain/range (nil = keep current)
`C:scaleToFitData()`	-	Auto-fits scale to include all data points with 10% margin
`C:draw(width, height, dt)`	-	Main render call; draws grid, data points, splines, crosshair
`C:overlayTextLines(lines)`	`lines: {string, ...}`	Overlays text lines on the graph
`C:generateCatmullSplinePoints()`	-	Pre-computes Catmull-Rom interpolation curves
`C:graphPtToImSS(x, y, clamp)`	-	Converts graph coords to ImGui screen-space
`C:graphPtToImWS(x, y)`	-	Converts graph coords to ImGui window-space

Usage Example

local plotHelper = require('/lua/ge/extensions/editor/util/plotHelperUtil')

-- Create a plot instance
local plot = plotHelper({
  scale = {xMin = 0, xMax = 100, yMin = 0, yMax = 200},
  autoScale = true,
  showCatmullRomCurve = true,
  catmullromCurveLines = 20,
  allowZoom = true,
  pointSize = 4,
  pointThickness = 2,
  formatX = "%0.1f",
  formatY = "%0.1f"
})

-- Set multi-series data: torque and power curves
local torqueData = {{1000, 80}, {2000, 140}, {3000, 180}, {4000, 200}, {5000, 190}}
local powerData = {{1000, 12}, {2000, 42}, {3000, 81}, {4000, 120}, {5000, 142}}

plot:setDataMulti({torqueData, powerData})
plot:setSeriesNames({"Torque (Nm)", "Power (kW)"})
plot:setSeriesColors({{1, 0.3, 0, 1}, {0, 0.6, 1, 1}})

-- Add annotation at peak torque
plot:setAnnotationX({{4000, "Peak Torque"}})

-- Draw in an ImGui window each frame
local dt = imgui.GetIO().DeltaTime
plot:draw(400, 300, dt)

-- Overlay stats
plot:overlayTextLines({"Peak: 200 Nm @ 4000 RPM"})

-- Interactive controls (built-in):
-- * Left-click drag to pan
-- * Mouse scroll to zoom
-- * Double-click to reset (via external logic)
-- * Hover data points for tooltips
-- * Crosshair follows cursor

Additional Internal Methods

Method	Description
`C:moveGraph(dt)`	Handles mouse-drag panning
`C:zoomGraph(dt)`	Handles scroll-wheel zoom based on mouse position
`C:drawCatmullSpline()`	Renders pre-computed Catmull-Rom curves
`C:drawGridAndAxesLabels()`	Draws grid lines, border, and axis tick labels
`C:getOptimalTickIncrement(ticks, range)`	Computes best tick spacing (1/2/5 increments)
`C:drawData()`	Renders data points as circles with hover tooltips
`C:normToImSS(x, y)`	Normalized (0–1) → ImGui screen-space coords
`C:normToImWS(x, y)`	Normalized (0–1) → ImGui window-space coords
`C:roundToDigits(num, dec)`	Rounds number to specified decimal places
`C:getOrderOfMagnitude(num)`	Returns floor of log10(abs(num))
`C:scaleX(x)`	Maps normalized X to graph X value
`C:scaleY(y)`	Maps normalized Y to graph Y value

Plot Helper Utility

Class: `C` (returned by factory function)

Usage Example

Additional Internal Methods

See Also

On this page

Plot Helper Utility

Class: `C` (returned by factory function)

Usage Example

Additional Internal Methods

See Also

On this page