🖉 Pencil.js

Nice modular interactive 2D drawing library.

Installation

You can install the whole package with the following command :

npm install pencil.js

But, each part is a JS module and can be used independently, ex:

npm install @pencil.js/scene

CDN

If you want to go old-school, you can fetch the script with unpkg or jsdelivr.

<script src="https://unpkg.com/pencil.js"></script>
<!-- or -->
<script src="https://cdn.jsdelivr.net/npm/pencil.js"></script>

<script>
    const scene = new Pencil.Scene();
</script>

Usage

Once you have installed it, you can start to import it using common.js or ES6 syntax.

There's multiple ways to rely on the project for your, pick the one that fits you need or preference :

// The whole package under a namespace
import Pencil from "pencil.js";

const scene = new Pencil.scene();

/***/

// Just the part you need
import Scene from "@pencil.js/scene";
// or
import Scene from "pencil.js";

const scene = new Scene();

/***/

// Works the same way with common.js syntax
const Scene = require("pencil.js").Scene;
// or
const Scene = require("@pencil.js/scene");

Since today's web browser don't support module requirements yet, you need to use a bundler like webpack or browserify.

Purpose

Abstraction

Drawing in a canvas is not trivial. First of all, the goal is to ease the use of canvas in a browser; allowing anyone to use it with its comprehensible syntax and extensible options.

OOP

OOP is great, OOP is almighty, OOP saves lives ! Others library exists, but none with a beautiful OOP syntax. It makes code look natural.

Modularity

Splitting the whole code into modules make everything cleaner. It also allow you to grab only what you need or replace what you don't like.

Documentation

A complete documentation goes a long way to help developers. All functions are assured to have a description and also typed arguments and returns.

Examples

import Scene from "pencil.js"; // or "@pencil.js/scene"
import Rectangle from "pencil.js"; // or "@pencil.js/rectangle"
import Position from "pencil.js"; // or "@pencil.js/position"

const scene = new Scene(); // create a new scene

const width = 80;
const height = 50;
const rectangle = new Rectangle(new Position(100, 200), width, height, {
    fill: "red"
}); // Create a new red rectangle
scene.add(rectangle); // Add the rectangle to the scene

scene.render(); // Render the scene once

Take a look at more advanced examples.

Or read the full documentation.

Modules

• EventEmitter
  • Container
    • Scene
    • Component
      • .draggable()
      • Path
      • Line
        • Spline
      • Polygon
        • RegularPolygon
          • Star
          • Triangle
      • Rectangle
        • .resizable()
        • Square
        • Image
      • Arc
        • Circle
      • Text
  • Input
    • Button
    • Checkbox
    • Slider
• Position
• Vector
• Math
• OffScreenCanvas
• BaseEvent
  • MouseEvent
  • KeyboardEvent

Common pitfalls

Scaling

Even if Pencil.js can draw thousand of shapes, it's not built around performance nor memory management. If you want to code an efficient particle generator, try Processing instead.

Naming

Some module have the same name as some Javascript global (eg: Image, Math). Importing them without namespace will overrides these globals and lead to potential bugs.

In any case, we recommend you use a namespace (eg: import Namespace from "pencil.js", import * as Namespace from "@pencil.js/math")

Contributions

You want to help us improve ? Please read the contributing manual.

Contributors

GMartigny