Node JS support package for LightningChart JS.
This package uses JSDOM, node-canvas and headless-gl to bring the LightningChart JS to Node JS.
node-gyp
is required on some platforms. See the documentation for node-gyp for installation instructions.
Only Ubuntu is currently officially supported. @lightningchart/lcjs-headless
most likely works on other distributions but might require extra work.
Requirements:
- Python 2.7
- GNU C++ environment (
build-essential
package fromapt
) - libxi-dev
- OpenGl driver (Mesa 3D)
- Glew
- pkg-config
$ sudo apt-get install -y build-essential libxi-dev libglu1-mesa-dev libglew-dev pkg-config
See headless-gl system dependencies for more details.
Install both @lightningchart/lcjs-headless
and @lightningchart/lcjs
from npm.
npm install @lightningchart/lcjs-headless @lightningchart/lcjs
When creating a new chart make sure to import the lightningChart()
function from @lightningchart/lcjs-headless
instead of @lightningchart/lcjs
. Other LightningChart JS related imports can be imported from @lightningchart/lcjs
.
To render a chart to a buffer, call chart.engine.renderFrame(width, height)
. This function will provide you a buffer containing a single image.
import { lightningChart } from "@lightningchart/lcjs-headless";
const lc = lightningChart({
license: "my-deployment-license-key",
licenseInformation: "my-deployment-license-information",
});
const chart = lc.ChartXY();
chart.engine.renderFrame(1280, 720);
The @lightningchart/lcjs-headless
package provides a couple of helper functions to make the use of LightningChart JS in Node JS environment easier. You can render an image directly to a sharp
or pngjs
objects with renderToSharp
and renderToPNG
helper functions.
import { lightningChart, renderToSharp } from "@lightningchart/lcjs-headless";
const lc = lightningChart({
license: "my-deployment-license-key",
licenseInformation: "my-deployment-license-information",
});
const chart = lc.ChartXY();
renderToSharp(chart, 1920, 1080).toFile("out.png");
const fs = require("fs");
const { PNG } = require("pngjs");
const {
lightningChart,
renderToPNG,
} = require("@lightningchart/lcjs-headless");
const lc = lightningChart({
license: "my-deployment-license-key",
licenseInformation: "my-deployment-license-information",
});
const chart = lc.ChartXY();
const chartOutput = renderToPNG(chart, 1920, 1080);
const outputBuff = PNG.sync.write(chartOutput);
fs.writeFileSync("./chartOutput.png", outputBuff);
When using Map Chart with in Node JS you need to provide the path to the LCJS resource files. To do this provide resourcesBaseUrl
with fs:
prefix.
const lcjs = lightningChart({
license: "my-deployment-license-key",
licenseInformation: "my-deployment-license-information",
resourcesBaseUrl: `fs:${path.resolve(
__dirname,
"node_modules",
"@lightningchart",
"lcjs",
"dist",
"resources"
)}`,
});
When running lcjs-headless in a Linux environment that doesn't provide a X11 or OpenGL environment you will need two more packages to make the environment ready for lcjs-headless.
xvfb-run -s "-ac -screen 0 1280x720x24" <node program>
There is a few helper methods available that are exported by this package.
- Requires
sharp
package to be installed. https://sharp.pixelplumbing.com/- Also install
@types/sharp
if you are using TypeScript
- Also install
- Prepares the frame to a "sharp" object, which allows the use of
sharp
to manipulate the image further or export it to a many different image formats.
import { lightningChart, renderToSharp } from "@lightningchart/lcjs-headless";
const lc = lightningChart({
license: "my-deployment-license-key",
licenseInformation: "my-deployment-license-information",
});
const chart = lc.ChartXY();
renderToSharp(chart, 1920, 1080).toFile("out.png");
Note: There is a known issue with using
sharp
on Windows. https://sharp.pixelplumbing.com/install#canvas-and-windows
- Requires
pngjs
package to be installed. https://github.com/lukeapage/pngjs- Also install
@types/pngjs
if you are using TypeScript.
- Also install
- Prepares the frame to a PNG image which can then be written to disk.
const fs = require("fs");
const { PNG } = require("pngjs");
const chartOutput = renderToPNG(chart, 1920, 1080);
const outputBuff = PNG.sync.write(chartOutput);
fs.writeFileSync("./chartOutput.png", outputBuff);
- Requires
pngjs
package to be installed. https://github.com/lukeapage/pngjs- Also install
@types/pngjs
if you are using TypeScript.
- Also install
- Uses the
pngjs
package to encode the raw RGBA data to a PNG and then encodes the buffer to a base 64 string.
- Requires
pngjs
package to be installed. https://github.com/lukeapage/pngjs- Also install
@types/pngjs
if you are using TypeScript.
- Also install
- Uses the
pngjs
package to encode the raw RGBA data to a PNG and then encodes the buffer to a base 64 string and adds the required data uri string.
- Creates a raw Node JS buffer from the UInt8Array that is returned by the
chart.engine.renderFrame
.
Different font's can be easily used.
The font is specified in the application code just like you would specify it when using LightningChart JS in browser.
If the font is not a system font, then it needs to be registered before it can be used. Registering should be done before any chart is created. Registering can be done with registerFont
function. If the font is not found, then a default font for the system will be used.
This function is re-exported by this package from the node-canvas
package.
import { lightningChart, registerFont } from "@lightningchart/lcjs-headless";
// Register Open Sans font from a font file
registerFont("OpenSans-Regular.ttf", { family: "Open Sans" });
// Create a chart
const lc = lightningChart({
license: "my-deployment-license-key",
licenseInformation: "my-deployment-license-information",
});
const chart = lc.ChartXY();
// Use the registered font
chart.setTitleFont((f) => f.setFamily("Open Sans"));
Anti-aliasing that is normally available in browsers is not available when using LightningChart JS in Node environment.
The devicePixelRatio
option when creating a chart can be used to render the chart with higher resolution while scaling all elements so that when the image is downsampled to the target resolution it's displayed correctly but with the benefits of using higher resolution. Rendering at higher resolution is more work so the rendering is slower.
import { lightningChart, renderToSharp } from "@lightningchart/lcjs-headless";
// Create a chart
const lc = lightningChart({
license: "my-deployment-license-key",
licenseInformation: "my-deployment-license-information",
});
// Create the chart with a devicePixelRatio 3 to render at higher resolution for downsampling
const chart = lc.ChartXY({ devicePixelRatio: 3 });
// render the chart to a sharp object
// the renderToSharp has built in support for downsampling by providing the pixelRatio as the fourth parameter
renderToSharp(chart, 1920, 1080, false, 3).toFile("out.png");
Only the renderToSharp
helper has a built in scaling to downsample the image.
Other helpers or using the chart.engine.renderFrame
method do not have built in scaling, instead these APIs will return the image at a resolution that is multiplied by the devicePixelRatio.
Make sure to install fontconfig
package.
If the font is not a system font, you will need to register the font file with registerFont
function.