Atrament

A small JS library for beautiful drawing and handwriting on the HTML Canvas...

DrawingCanvas
jakubfiala/atramentfiala.space/atrament/demoatrament

README

Atrament


A small JS library for beautiful drawing and handwriting on the HTML Canvas


undefined

Atrament is a library for drawing and handwriting on the HTML canvas.
Its goal is for drawing to feel natural and comfortable, and the result to be smooth and pleasing.
Atrament does not store the stroke paths itself - instead, it draws directly onto the canvas bitmap,
just like an ink pen onto a piece of paper ("atrament" means ink in Slovak and Polish).
This makes it suitable for certain applications, and not quite ideal for others.

⚠️ Note: From version 4, Atrament will only support evergeen browsers (Firefox, Chrome and Chromium-based browsers)
and Safari 15 or above. If your application must support older browsers, please use version 3.

Features:

- Draw/Fill/Erase modes
- Adjustable adaptive smoothing
- Events tracking the drawing - this allows the app to "replay" or reconstruct the drawing, e.g. for undo functionality
- Adjustable line thickness and colour

Here's a basic demo.

Enjoy!

- Atrament
  - Installation
  - Usage
  - Options \& config
  - Data model
  - Events
    - Dirty/clean
    - Stroke start/end
    - Fill start/end
    - Stroke recording
  - Programmatic drawing
  - Development

Installation


If you're using a tool like rollup or webpack to bundle your code, you can install it using npm.

- install atrament as a dependency using npm install --save atrament.
- You can access the Atrament class using import { Atrament } from 'atrament';

Usage


- create a `` tag, e.g.:

  1. ```html
  2. <canvas id="sketchpad" width="500" height="500"></canvas>
  3. ```

- in your JavaScript, create an Atrament instance passing it your canvas object:

  1. ```js
  2. import Atrament from 'atrament';

  4. const canvas = document.querySelector('#sketchpad');
  5. const sketchpad = new Atrament(canvas);
  6. ```

- you can also pass the width, height and default colour to the constructor:

  1. ```js
  2. const sketchpad = new Atrament(canvas, {
  3.   width: 500,
  4.   height: 500,
  5.   color: 'orange',
  6. });
  7. ```

- that's it, happy drawing!

Options & config


- clear the canvas:

  1. ```js
  2. sketchpad.clear();
  3. ```

- change the line thickness:

  1. ```js
  2. sketchpad.weight = 20; //in pixels
  3. ```

- change the color:

  1. ```js
  2. sketchpad.color = '#ff485e'; //just like CSS
  3. ```

- toggle between modes:

  1. ```js
  2. import { MODE_DRAW, MODE_ERASE, MODE_FILL, MODE_DISABLED } from 'atrament';

  4. sketchpad.mode = MODE_DRAW; // default
  5. sketchpad.mode = MODE_ERASE; // eraser tool
  6. sketchpad.mode = MODE_FILL; // click to fill area
  7. sketchpad.mode = MODE_DISABLED; // no modification to the canvas (will still fire stroke events)
  8. ```

- tweak smoothing - higher values make the drawings look much better, lower values make drawing feel a bit more responsive. Set to 0.85 by default.

  1. ```js
  2. sketchpad.smoothing = 1.3;
  3. ```

- toggle adaptive stroke, i.e. line width changing based on drawing speed for a more natural effect. true by default.

  1. ```js
  2. sketchpad.adaptiveStroke = false;
  3. ```

- record stroke data (enables the strokerecorded event). false by default.

  1. ```js
  2. sketchpad.recordStrokes = true;
  3. ```

Data model


- Atrament models its output as a set of independent _strokes_. Only one stroke can be drawn at a time.
- Each stroke consists of a list of _segments_, which correspond to all the pointer positions recorded during drawing.
- Each segment consists of a _point_ which contains x and y coordinates, and a time which is the number of milliseconds since the stroke began, until the segment was drawn.
- Each stroke also contains information about the drawing settings at the time of drawing (see Events > Stroke recording).

Events


Dirty/clean


These events fire when the canvas is first drawn on, and when it's cleared.
The state is stored in the isDirty property.

  1. ```js
  2. sketchpad.addEventListener('dirty', () => console.info(sketchpad.isDirty));
  3. sketchpad.addEventListener('clean', () => console.info(sketchpad.isDirty));
  4. ```

Stroke start/end


These events don't provide any data - they just inform that a stroke has started/finished.

  1. ```js
  2. sketchpad.addEventListener('strokestart', () => console.info('strokestart'));
  3. sketchpad.addEventListener('strokeend', () => console.info('strokeend'));
  4. ```

Fill start/end


These only fire in fill mode. The fillstart event also contains x and y properties
denoting the starting point of the fill operation (where the user has clicked).

  1. ```js
  2. sketchpad.addEventListener('fillstart', ({ x, y }) =>
  3.   console.info(`fillstart ${x} ${y}`),
  4. );
  5. sketchpad.addEventListener('fillend', () => console.info('fillend'));
  6. ```

Stroke recording


The following events only fire if the recordStrokes property is set to true.

strokerecorded fires at the same time as strokeend and contains data necessary for reconstructing the stroke.
segmentdrawn fires during stroke recording every time the draw method is called. It contains the same data as strokerecorded.

  1. ```js
  2. sketchpad.addEventListener('strokerecorded', ({ stroke }) =>
  3.   console.info(stroke),
  4. );
  5. /*
  6. {
  7.   segments: [
  8.     {
  9.       point: { x, y },
  10.       time,
  11.     }
  12.   ],
  13.   color,
  14.   weight,
  15.   smoothing,
  16.   adaptiveStroke,
  17. }
  18. */
  19. sketchpad.addEventListener('segmentdrawn', ({ stroke }) =>
  20.   console.info(stroke),
  21. );
  22. ```

Programmatic drawing


To enable functionality such as undo/redo, stroke post-processing, and SVG export in apps using Atrament, the library
can be configured to record and programmatically draw the strokes.

The first step is to enable recordStrokes, and add a listener for the strokerecorded event:

  1. ```js
  2. atrament.recordStrokes = true;
  3. atrament.addEventListener('strokerecorded', ({ stroke }) => {
  4.   // store `stroke` somewhere
  5. });
  6. ```

The stroke can then be reconstructed using methods of the Atrament class:

  1. ```js
  2. // set drawing options
  3. atrament.mode = stroke.mode;
  4. atrament.weight = stroke.weight;
  5. atrament.smoothing = stroke.smoothing;
  6. atrament.color = stroke.color;
  7. atrament.adaptiveStroke = stroke.adaptiveStroke;

  9. // don't want to modify original data
  10. const segments = stroke.segments.slice();

  12. const firstPoint = segments.shift().point;
  13. // beginStroke moves the "pen" to the given position and starts the path
  14. atrament.beginStroke(firstPoint.x, firstPoint.y);

  16. let prevPoint = firstPoint;
  17. while (segments.length > 0) {
  18.   const point = segments.shift().point;

  20.   // the `draw` method accepts the current real coordinates
  21.   // (i. e. actual cursor position), and the previous processed (filtered)
  22.   // position. It returns an object with the current processed position.
  23.   const { x, y } = atrament.draw(point.x, point.y, prevPoint.x, prevPoint.y);

  25.   // the processed position is the one where the line is actually drawn to
  26.   // so we have to store it and pass it to `draw` in the next step
  27.   prevPoint = { x, y };
  28. }

  30. // endStroke closes the path
  31. atrament.endStroke(prevPoint.x, prevPoint.y);
  32. ```

Development


To obtain the dependencies, cd into the atrament directory and run npm install.
You should be able to then build atrament by simply running npm run build.

I didn't bother writing tests because it's such a small package. Contributions are welcome!