waterbox-canvas

A simple library that renders an isometric water box on a canvas

waterbox-canvas is a TypeScript/JavaScript library for rendering a water level visualization on an HTML5 Canvas or OffscreenCanvas.

Demo

Check out the demo on the project page or head over to StackBlitz to fiddle around.

Installation

NPM

npm install waterbox-canvas

Yarn

yarn add waterbox-canvas

PNPM

pnpm add waterbox-canvas

Browser (Direct Include)

There is a build specifically for the browser:

<script src="dist/waterbox-canvas.browser.js"></script>

Basic Usage

Create a canvas element:

<canvas id="my-canvas"></canvas>

Create Waterbox:

import { createWaterbox } from 'waterbox-canvas';

const canvas = document.getElementById('my-canvas') as HTMLCanvasElement;

// Create a waterbox instance
const waterbox = createWaterbox(canvas)
  .width(80)
  .height(120);

// Set the water level (0-100)
waterbox.value(50);

// Render the waterbox
waterbox.render();

Example

import { createWaterbox } from 'waterbox-canvas';

// Initialize waterbox
const canvas = document.getElementById('waterbox') as HTMLCanvasElement;

const waterbox = createWaterbox(canvas)
  .width(80)
  .height(120)
  .padding(5)
  .tiltAngle(30)
  .backColorScheme({
    fill: 'rgba(192,192,224,1.0)',
    stroke: 'rgba(127,127,192,1.0)',
    contrast: 0.1,
  })
  .waterColorScheme({
    fill: 'rgba(64,64,224,0.6)',
    stroke: 'rgba(64,64,224,0.6)',
    contrast: 0.1,
  })
  .scale({
    divisions: 5,
    size: 0.2,
  })
  .strokeWidths({
    inner: 1,
    outer: 3,
  });

waterbox.value(20).render();

API Reference

createWaterbox(canvas: HTMLCanvasElement | OffscreenCanvas): Waterbox

Creates a new waterbox instance for the given canvas.

Parameters:

• canvas - The HTML canvas or OffscreenCanvas element to render to

Returns: A Waterbox instance

Waterbox properties

width

• width(): number
• width(value: number): Waterbox

Get or set the width of the canvas.

height

• height(): number
• height(value: number): Waterbox

Get or set the height of the canvas.

padding

• padding(): number
• padding(value: number): Waterbox

Get or set the padding of the drawn waterbox.

value

• value(): number
• value(value: number): Waterbox

Get or set the water fill level.

tiltAngle

• tiltAngle(): number | undefined
• tiltAngle(value?: number): Waterbox

Get or set the isometric tilt angle

backColorScheme

• backColorScheme(): ColorScheme
• backColorScheme(value: ColorScheme): Waterbox

Get or set the color scheme of the backside of the rendered waterbox.

Example

waterbox.backColorScheme({
  fill: 'rgba(80, 80, 111, 1)',
  stroke: 'rgba(80, 80, 111, 1)',
  contrast: 0.1
});

waterColorScheme

• waterColorScheme(): ColorScheme
• waterColorScheme(value: ColorScheme): Waterbox

Get or set the color scheme of the water rendered inside the waterbox.

Example

waterbox.waterColorScheme({
  fill: 'rgba(58, 123, 213, 0.9)',
  stroke: 'rgba(42, 92, 160, 0.9)',
  lighter: 'rgba(90, 149, 224, 0.9)',
  darker: 'rgba(43, 95, 168, 0.9)',
});

frontColorScheme

• frontColorScheme(): ColorScheme | undefined
• frontColorScheme(value?: ColorScheme): Waterbox

Get or set the color scheme of the front of the rendered waterbox.

Example

waterbox.frontColorScheme({
  fill: 'rgba(255, 255, 255, 0.1)',
  innerStroke: 'rgba(255, 255, 255, 0.05)',
  outerStroke: 'rgba(255, 255, 255, 0.5)',
  contrast: 0.1,
});

backPattern

• backPattern(): Pattern | undefined
• backPattern(value?: Pattern): Waterbox

Get or set the pattern drawn on top of the backside of the waterbox.

Example

waterbox.backPattern({
  name: "grid",
  size: 15,
  alpha: 1.0
});

waterPattern

• waterPattern(): Pattern | undefined
• waterPattern(value?: Pattern): Waterbox

Get or set the pattern drawn on top of the water.

Example

waterbox.waterPattern({
  creator: (ctx) => {
    // render pattern
    return ctx.createPattern(patternCanvas, 'repeat');
  } 
});

frontPattern

• frontPattern(): Pattern | undefined
• frontPattern(value?: Pattern): Waterbox

Get or set the pattern drawn on top of the front of the waterbox.

strokeWidths

• strokeWidths(): StrokeWidths
• strokeWidths(value: StrokeWidths): Waterbox

Get or set the stroke inner and outer widths in pixels.

Example

waterbox.strokeWidths({
  inner: 1,
  outer: 2
});

scale

• scale(): Scale | undefined
• scale(value?: Scale): Waterbox

Get or set the scale drawn in the waterbox.

Example

waterbox.scale({
  size: 0.2,
  divisions: 5,
  position: 'back',
});

clipEdges

• clipEdges(): boolean
• clipEdges(value: boolean): Waterbox

Get or set whether edges are clipped from the drawn waterbox. If edges are clipped, they appear as transparent.

options

• options(): Options
• options(value: Partial<Options>): Waterbox

Get or set multiple options at once.

License

MIT