CS114 Project 3:
Cloth Simulation using Mass-Spring System

Due: Thursday May 16, 2019 (23:59 pm Pacific Time)


Download the project codebase here.

In this project, you will implement a simple cloth simulator for animating a rectangular piece of cloth.

1. Mass-Spring System

As discussed in class, we consider the cloth as a collection of particles interconnected with three types of springs: The rest of this section details this mass-spring system.

1.1. Particles

We assume the cloth contains $n \times n$ (evenly spaced) particles and use $[i, j]$ (where $0 \leq i, j < n$) to denote the particle located at the $i$-th row and $j$-th column. Each particle $[i, j]$ has the following states:

The position and velocity of a particle are affected by various types of forces (see Section 1.3). In particular, assuming the accumulated force acting on particle $[i, j]$ at time $t$ to be $\mathbf{F}_{i, j}(t)$, then Newton's second law of motion tells us that the acceleration of this particle at time $t$ equals $$\mathrm{a}_{i, j}(t) = \dot{\mathbf{v}}_{i,j}(t) = \ddot{\mathbf{x}}_{i,j}(t) = \frac{\mathbf{F}_{i, j}(t)}{m}.$$

1.2. Springs

There are three types of springs connecting all particles: structural, shear, and flexion (bend).

Thus, each particle can have up to 12 directly connected neighbors.

Stiffness: in this project, we assume all structural springs to have stiffness $K_0$, shear springs $K_1$, and flexion strings $K_2$.

Rest length: generally, a piece of cloth is considered to be in its rest state when there is no deformation (caused by stretching, shearing, or bending). In this project, the original shape of the cloth is a rectangle of size $4 \times 4$. It follows that the rest lengths for all structural, shear, and flexion springs are $4/(n - 1)$, $4\sqrt{2}/(n - 1)$, and $8/(n - 1)$, respectively.

1.3. Forces

There are four types of forces you will need to consider for this project:

2. Animating the System

As mentioned in class, animating a mass-spring system involves solving an initial value problem. In particular, for each particle $[i, j]$ you are given its mass $m$ (which stays constant for all particles), initial position $\mathbf{x}_{i,j}(0)$ and velocity $\mathbf{v}_{i,j}(0)$. Given $\Delta t > 0$, you need to use Euler's method to compute the position and velocity of each particle at time-steps $\Delta t$, $2 \Delta t$, $3 \Delta t$, $\ldots$.

You need to pin two particles $[n - 1, 0]$ and $[n - 1, n - 1]$, which correspond to the upper left and right corners of the cloth. That is, the positions of these particles are fixed to their inital values. If no particle is pinned in place, the entire cloth will undergo a never-ending free fall because of gravity!

2.1. Codebase Overview

A WebGL based codebase similar to Project 1 has been provided. This time, the only source file you will need to touch is proj3_sim.js.

It is recommended to use Google Chrome for executing your code, although recent versions of Mozilla Firefox should also work.


A key class that you will be using is vec3 from glMatrix version 0.9.5. Useful member functions include vec3.create(), vec3.add(), vec3.subtract(), vec3.scale(), vec3.length(), vec3.normalize(), and vec3.dot(). Check js/glMatrix-0.9.5.js to see how they work.

Reminder: several functions such as vec3.add(), vec3.subtract(), and vec3.scale() operate in place. That is, calling vec3.add(a, b) will cause the value of a changing to a + b. If you do NOT want a to be modified, create a copy of it using vec3.create(). For instance, c = vec3.add(vec3.create(a), b) will make c to have the value a + b without changing the value of a.

Global Variables

A number of global variables are used to store various mass-spring system configurations and particle states.

Constants (time-invariant):

All the time-invariant constants have been handled by the provided code. You can directly access them in your code.

Particle states (time-variant):

Global Functions

A number of getter & setter functions are provided for your convenience:

2.2. Function to Complete

Opening proj3.html in your browser will lead to a piece of cloth that stays still: You will need to finish the key function simulate() in proj3_sim.js to animate the cloth.

This function takes one parameter stepSize (i.e, $\Delta t$) and performs ONE iteration of Euler's method. Precisely, assuming vertexPosition and vertexVelocity currently stores the position $\mathbf{x}_{i,j}(t)$ and velocity $\mathbf{v}_{i,j}(t)$ for each particle $[i, j]$ at time $t$. After executing simulate() once, vertexPosition and vertexVelocity should be updated so that they store $\mathbf{x}_{i,j}(t + \Delta t)$ and $\mathbf{v}_{i,j}(t + \Delta t)$, respectively.

To achieve this, you will need to do the following:

  1. Compute the accumulated force $\mathbf{F}_{i, j}$ acting on each particle $[i, j]$ for $i, j \in \{0, 1, \ldots, n - 1\}$ based on each particle's current position and velocity.
  2. Update the velocity of each particle using $$\mathbf{v}_{i, j} \gets \mathbf{v}_{i, j} + \Delta t\,\frac{\mathbf{F}_{i,j}}{m}.$$
  3. Update the position of each particle (except for the two pinned ones which stay static) using $$\mathbf{x}_{i, j} \gets \mathbf{x}_{i, j} + \Delta t\cdot\mathbf{v}_{i, j}.$$ Notice that the updated velocity $\mathbf{v}_{i, j}$ (from Step 2) is used here for better numerical stability.

With simulate() properly implemented, we should see the cloth deforming. Here we show an example frame: Please submit your finished proj3_sim.js to EEE.