React Pixi Plot

A React component rendering a zoomable and draggable PIXI.js scene. Intended to render 2d plots

Do I need this?

If your project uses React, and you need to render a large number of elements in an interactive 2D scene, then maybe this small library is for you.

With the help of the SVGGraphics class (adapted from saschagehlich/pixi-svg-graphics) you can also easily use the SVG paths generated by D3.js

Installation

npm install --save @thechiselgroup/react-pixi-plot react pixi.js

Basic Usage

1. Create an array of PIXI.DisplayObjects (e.g. Graphics) and assign a position to them
2. Import PixiPlot: import {PixiPlot} from '@thechiselgroup/react-pixi-plot'
3. Render the PixiPlot component: <PixiPlot displayObjects={myDisplayObjects} size={{width: 1024, height: 768}} />

PixiPlot will automatically detect the bounds of the display objects and adapt the scale and position of the plot container to perform a "zoom to fit"

Extended Usage

PixiPlot handles a number of optional props that can be useful to respond to user interaction. Here is the complete list of props supported by PixiPlot

• displayObjects: PIXI.DisplayObject[] : An array of DisplayObject that will be added to the plot container. The elements contained in this array can be mutated, but the array itself cannot be mutated. The changes will be handled by PIXI, not react. If a new array of objects is passed, a zoomToFit will be triggered.

• size: {height: number, width: number} : The size of the plot, in pixels

• dirty?: number: This prop is used to trigger a re-render of the PIXI stage (anytime this number changes, the stage is re-rendered). This is useful when you change the properties of the display objects

• displayObjectsInFront?: PIXI.DisplayObject[] : An array of DisplayObject that should appear in the foreground. The elements in this array should also be included in the displayObjects array. Every time this prop changes, the elements in the plot container will be re-ordered accordingly. The last element of this array will be the foremost element displayed.

• displayObjectsBounds?: PIXI.Rectangle: A Rectangle defining the bounds of the display objects. This is use for the initial rendering of the plot, when computing the scale and position of the plot container. If ommited, the getBounds method from the plot container will be used instead.

• rendererMargins?: {left: number, right: number, top: number, bottom: number}: The margins around the renderer, where you can display axes for instance

• stageMargins?: {left: number, right: number, top: number, bottom: number}: The margins around the stage, in pixels.

• keepAspectRatio?: boolean: If true, the x and y scales will be identical

• invertYScale?: boolean: By default the y axis goes from top to bottom. You may want to invert it if you do not scale the display objects' positions outside of PixiPlot

Interaction props

• onSelect?: (e: SelectEvent, target: PixiPlot) => void: This callback is invoked whenever the user clicks or brushes on the plot.

• onHover?: (e: HoverEvent, target: PixiPlot) => void: This callback is invoked whenever the user hovers on the plot, or while brushing.

Life-cycle props

• scaleWillUpdate?: (nextXScale: number, nextYScale: number, target: PixiPlot) => void: Invoked after the next value for the scale is computed, but before re-rendering. This is a good place to update the plot if needed.

• positionWillUpdate?: (nextPos: PIXI.Point, target: PixiPlot) => void: Invoked after the next value for the position is computed, but before re-rendering. This is a good place to update the plot if needed.

• scaleDidUpdate?: (target: PixiPlot) => void: Invoked after the scale was updated, and after the stage re-rendered.

• positionDidUpdate?: (target: PixiPlot) => void:Invoked after the position was updated, and after the stage re-rendered.

• shouldXPositionUpdate?: (nextXPos: number, target: PixiPlot) => boolean: Invoked before any change is made to the x component of the stage position. If it returns false, the x component of the position will not change.

• shouldYPositionUpdate?: (nextYPos: number, target: PixiPlot) => boolean: Invoked before any change is made to the y component of the stage position. If it returns false, the y component of the position will not change.

• shouldXScaleUpdate?: (nextXScale: number, isZooming: boolean, isResizing: boolean, target: PixiPlot) => boolean: Invoked before any change is made to the x component of the stage scale. If it returns false, the x component of the scale will not change.

• shouldYScaleUpdate?: (nextYScale: number, isZooming: boolean, isResizing: boolean, target: PixiPlot) => boolean: Invoked before any change is made to the y component of the stage scale. If it returns false, the y component of the scale will not change. Intended to be redefined to use parameter.

Examples

TODO (see the examples directory)

Work in progress

• Currently, a brush interaction (left click and drag) will show a rectangular selection overlay. We plan to make this selection overlay customizable.