A quick start guide to Pt

This is an introduction to Pt. Pt is experimental and fun. You can read more about the motivations here.

This guide will talk about the basic concepts of Pt, and I would like it to be understandable to people who are learning to code. Please bear with me if it seems dull at times.

I’ll just assume you can read basic html and javascript code and nothing else. If you already know javascript well, check out the demos and the docs. If you like spoiler, this is what we’ll be building in this guide.

Let’s get started then. We’ll first create an html file, which grants us the power to show cats and stuff on the interweb. (If you don’t have a text editor for coding, try the free Atom editor .) Let’s save it as start.html. It looks like this:

Inside `<head>`, we add a title and include the pt javascript library file.
And inside `<body>`, we add a 500px by 500px container element,
and also include another `<script>` block, into which the most exciting code will go.

Next, we will jump start our artistic career by drawing a dot.


Pt is based on the concepts of Point, Form, and Space. For simplicity, let’s imagine Space as your canvas, Form as your brush, and Point as your idea.

Our most exciting code starts off by creating a space in javascript, like this:

What this means is that we'll create a Space using html5 canvas.
By default, this will look for an element in your html that has an attribute id="pt", and add a `<canvas>` element inside it.

We can customize this by passing parameters into it. Using `setup({…})`, you can optionally specify background color and other things.

The code above will create a canvas with a light grey background, displayed inside a container element whose id="pt".

Done! The advanced coder will notice (with furious anger) that we’re missing stuff like the damn semicolon and the annoying var and the sacred namespace. Let’s not worry about being correct for now. Let’s have fun and make a mess!

Next we’ll make the Form, which is like our brush. The basic Form class that comes with Pt will work with CanvasSpace. We just need to create it like this: `form = new Form(space)`

Notice the Form takes a parameter, which is the space we just created. This defines the context and links the form to the space. In plain language, it’s saying we will be using this brush for this canvas.

You may ask: where is the action? Here is the action:

Let’s take a look at what’s going on.

First, we create a dot, which is a Point at position 250, 250 (x and y coordinates). See, it is a point in space. It is known.

Secondly, we need someone to pick up our brush and draw our dot. So we create a bot, which is a little robot to go into space and draw the dot. The robot has a function called animate.

When we put the robot in space, via `space.add( bot )`, it will execute the animate function, and do `form.point( dot )`, which draws the dot as a visible point.

And there are other convenient drawing functions in Form, such as `form.circle`, `form.triangle`, etc. You can even extend Form to draw all kinds of crazy stuff.

Lastly, after all these preparations, the space comes alive when we hit `space.play()`.

One quick note: The bot is an example of an object in javascript. Any object that defines an animate function can be added to a space using `space.add(…)`.

Let’s take a deep breadth, and behold this minimalistic beauty we’ve created.

During intermission, think about Point, Form, and Space a bit more. This scary looking diagram here is a recap of what we just discussed.

You may now get a coffee and come back for more exciting developments.


Perhaps the dot is not what you imagined it to be. Perhaps, like Kandinsky, you’re thinking about a metaphysical circle in blue color. Let’s revise the code like this:

What’s changed? Now the dot goes from a Point to a Circle, with its radius to 50. Inside the bot’s animate function, we pick a fill color of blue (#5AF is a hexadecimal rgb color) and no stroke color for our brush, and use it to draw a circle. Voila!

Notice the parameters `(time, fs, …)` in animate function? These help you keep track of the passing of time and doing things with it.

The first parameter time tells you, in milliseconds (1/1000th of a second) the time that has passed.

The second parameter fs indicates the time taken to refresh the drawing. (Think of an animation as a sequence of frames, shown one after another, each is displayed for some milliseconds). If you calculate 1000/fs, then you’ll know the current frame rate, ie, how many frames were shown per second. 60 frames-per-second is great, 30 fps is ok. But when frame-rate is low, side effects may include nausea, headache, and depression.

Let’s use Time to our advantage, and do something fun with it.

The code now looks a bit frightening, but it’s worth it because now our circle is pulsating! Let’s go through it.

First we set the fill color to a medium grey (#999), and use it to draw text at position (20, 20). We calculate the frame rate as 1000/fs and display it as text.

Then we modify the circle’s radius based on time. What does that crazy formula `Math.abs(500 - time % 1000)/20 + 20` mean?

If you imagine the time passing in 3 seconds or 3000 milliseconds:

0...1...345...1000...1231...1983...2000...2314...2781...3000

So if we divide by 1000 and take the remainder (`time % 1000`), we’ll get:

0...1...345...0......231....983....0......314....781....0

Then if we subtract it by 500 and make it an absolute value which is always positive ( Math.abs ), we’ll get this:

500..499.155..500....269....483....500....186....281...500

And we divide it by 20 to scale it down to the size we want:

25...25..8....25.....13.....24.....25.....9......14....25

So the final radius of the circle is set to be at least 20px, plus the dynamic value from time we just calculated: `Math.abs(…)/20 + 20`. As time passes, the circle will pulsate between radii from 20 to 45.

45...45..28...45.....33.....44.....45.....29.....34....45

And this is why I feel that code is like clay. With your mind’s eye, you can see it, and when you can see it, you can touch and mold it. It’s exciting. And it’s not brain surgery, is it?

Let’s mold it a bit more. What if we can make it move? First, we will create another circle, called another, obviously. Then we’ll ask the bot to draw it like what we did with the dot. The only difference is that we’ll draw it with no fill color, but with a 5px orange outline: `stroke(“#fc0”, 5)`.

Our bot can observe the “events” happening in space, such as when user clicks or moves the mouse. To set it up, we get all mouse events from space, via a helper function `space.bindMouse()`. Then, in addition to animate, we add another callback function in the bot called onMouseAction. So it looks like this:

The onMouseAction function has parameters `(type, x, y, evt)`. The parameter type gives you a “string”, which is a piece text to tell you what the type of action is, such as “move”, “drag”, “drop”, and “down”. The parameters x and y then gives you the current mouse position.

To move the another circle with the mouse, we can add some simple logic into onMouseAction:

If you move your mouse around, you should see the orange circle is following your cursor.

With a circle pulsating, and another moving with the mouse, we are now on the verge of a creative breakthough! One thing that Circle can do is to check if it intersects with another circle. Let’s try:

We start by checking for intersection using `another.intersectCicle( dot )`. If intersection occurs, this function will give us two intersection points in a list called an array. We store the points array in a variable called hits.

Next we check if hits array has more than 0 items in it, using an `if(…)` statement. In plain language, it says: if (hits array has more than 0 items), then do the things inside the curly braces { … }.

Here we draw the intersection points as circular points with 5px radius, by calling the convenient function `form.points(hits, 5, true)`. The last parameter value `true` means the point will be circular. If it’s set to `false` or omitted, then the points are rectangular.

And why stop here? For example, you can connect the hits points with a line. It’s as simple as:

We create a new Line by specifying its two end points as the hits points. We use the array index notation ( `something[0]` ) to get the point out of the array. Notice that the first item in an array is at position 0. Finally we asks our Form to draw the line: `form.line( … )`.

Whoa, take a look at what we have achieved with less than 40 lines of javascript code in a basic html file. Congratulations! Now it’s your turn to put your imaginative forces to work. Take a look at the demos, and the docs, and if you haven’t, learn to code.

And this is how this guide will end, not with a bang, but with some technical notes:

Have fun!