lua-plot

20 August 2019 Link

On This Page



Introduction

A plotting library for Lua based on IUP to create plots using the standard Lua Interpreter. The plots are managed by a separate thread and don't block the interpreter. It consists of a module that Lua can require to get the plotting API and separate file which is spawned as a separate thread that manages the plots so that it doesn't block the main Lua interpreter.

Dependencies

The module is depended on:
  1. Lua Socket - luasocket - used for communication between module and plot server thread
  2. Lua Low Level threads - llthreads - Used to create a separate thread to run the plot server
  3. IUP Lua - IUP _ used to create the plots and the windows
  4. lua-complex - Lua Complex numbers library - Used to handle complex numbers in bode plots

API

Here is the API to use the plotting library

Including the library

The library is required by doing:
lp = require "lua-plot"

The lp table has the following elements:
  1. _VERSION - contains the version number for lua-plot
  2. listPlots - this is a function without any arguments that lists out the plots currently maintained by the lua-plot module and also the list of plots the plot server has. NOTE The plot server may have additional plots since they are not garbage collected yet even when the plots are garbage collected in the script locally.
  3. plot - This function creates a plot. It needs a table to be passed to it containing the attributes as defined in iupPlot. It adds 1 attribute AXS_BOUNDS which can be a table array with index 1 = AXS_XMIN, 2 = AXS_YMIN, 3=AXS_XMAX, 4=AXS_YMAX. It returns the created plot object. The plot is not shown but is created.
  4. window - This function creates a window. It needs a table to be passed to it containing the window layout slots. It is a table array with n values where n is the number of rows needed in the window. Each value tells how many slots to be there in that row. So a table {2,2} creates a window with 2 rows with 2 slots each. The table can also have IUP dialog attributes as defined in iupPlot that will be applied to the dialog representing the window. It returns the created window object.
  5. bodePlot - This function creates a bode plot. It needs a table argument with certain keys:
    func - This key should have a function value. This is a single parameter function of the complex frequency s and returns a complex number for every s complex frequency (jw) from which the magnitude and phase can be computed and then plotted.
    ini - starting frequency in Hz of the plot (default = 0.01)
    finfreq - ending frequency of the plot (default = 1MHz)
    steps - number of steps per decade for the plot (default=50)
    Returns a bode plot table object

Plot Object

The plot object provides the following API:
  1. AddSeries: Adds a series of points to the plot object. Call it like:
    plot:AddSeries(xvalues,yvalues[,AttributesTable])
    or
    plot:AddSeries(xyPoints[,AttributesTable])
    xvalues - array of x value points
    yvalues - array of y value points (same size as that of xvalues or extra are ignored)
    xyPoints - array of points where each point is a table containing an x,y value pair. So such a table is like { {x1,y1}, {x2,y2}, ...{xn,yn} }
    AttributesTable - is a list of attributes to set on the plot object. For all attributes refer to iupPlot
    returns true for success or nil and error message in case of error
  2. Show: Shows a plot on the screen. If it is already there then brings focus to it. Call it like:
    plot:Show([AttributesTable])
    AttributesTable - is a list of attributes to set on the plot window. For all attributes refer to iupDialog
    returns true for success or nil and error message in case of error
  3. Redraw: Redraws the plot object. Call it like:
    plot:Redraw()
    returns true for success or nil and error message in case of error
  4. Attributes: Sets up attributes of the plot object. Call it like:
    plot:Attributes(AttributesTable)
    AttributesTable - is a list of attributes to set on the plot object. For all attributes refer to iupPlot
    returns true for success or nil and error message in case of error

Window Object

The window object provides the following API:
  1. AddPlot: This function adds an existing plot object to the window object. Call it like:
    window:AddPlot(plotObj,coordinate)
    plotObj - is the plot object that needs to be added
    coordinate - it is a table with 2 numbers specifying the slot coordinate where the plot needs to be placed. Example {1,2} specifies placing the plot in the 1st row second slot. Coordinates start from 1. The coordinate slot should exist and should be empty.
    returns true for success or nil and error message in case of error
  2. Show: Shows a window on the screen. If it is already there then brings focus to it. Call it like:
    window:Show()
    returns true for success or nil and error message in case of error
  3. ClearSlot: Clears a slot in the given window so that it becomes empty and a plot can be placed on it. It is only required if another plot was present there. Call it like:
    window:ClearSlot(coordinate)
    coordinate - it is a table with 2 numbers specifying the slot coordinate where the plot needs to be placed. Example {1,2} specifies placing the plot in the 1st row second slot. Coordinates start from 1. The coordinate slot should exist and should be empty.
    returns true for success or nil and error message in case of error

Bode Plot Object

The bode plot object consists of a table with the magnitude and phase plot objects. The table has the following members:
  1. mag - magnitude plot object. Can use all the plot object API with this.
  2. phase - phase plot object. Can use all the plot object API with this.
  3. addplot - function to add another bode plot to the same bode plot object. Call it like:
    bodePlot:addplot([func,legend])
    func - This is a function value. This is a single parameter function of the complex frequency s and returns a complex number for every s complex frequency (jw) from which the magnitude and phase can be computed and then plotted.
    legend - is the legend name for the added plot

Examples

Create a plot and add data to it:

lp = require("lua-plot")
p = lp.plot{}
p:Show()    -- shows a blank plot
p:AddSeries({ {1,1},{2,2},{3,3} })
p:Redraw()
-- The graph can be closed at this point by closing the window pressing the cross button
p:Show()   -- shows the graph again.
lp.listPlots()   -- displays the list of plots maintained locally and by the plotserver ( should be just 1)
p = nil      -- will cause the graph to be garbage collected
lp.listPlots()   -- will show no plots left

Download

The module can be downloaded from github