This is the documentation for a small program I wrote that simulates the behaviour of a piece of cloth draped over various shapes:
You can download the source code here (it includes this documentation) or a linux binary here. It is distributed under the GPL license. If anybody makes executables for other platforms, please let me know so I can add a link here.
Somebody made a windows executable here. Thanks!
The program takes an input file made of three parts: a
global_settings section, a cloth definition and object definitions.
The parts must appear in that order, but only the cloth section is mandatory. Here
is a very simple sample that drapes a piece of cloth over a cylinder (like a napkin over a round
table):
global_settings {
step 0.2
}
cloth {
x_size 50
y_size 50
}
cylinder { -2*z, -z, 20 } // Table top
/* Note that *z* is the up-pointing vector */
That's it. You can run it with cloth -itable.cl
-otable.inc -s20000 to produce the file table.inc which you can then include
into a POVray scene file:
#version unofficial MegaPov 0.6;
global_settings {
assumed_gamma 1.0
}
camera {
location 50*x-75*z+25*y
look_at -10*y
angle 40
}
light_source {
<1000, 1000, -1000>
rgb 1
}
object {
#include "table.inc"
uv_mapping
pigment {
object {
sphere { 1.5*x+y, 0.5 }
pigment {
object {
box { <0, 0.5, -0.5>, <1, 1.5, 0.5> }
color rgb 0.75
color rgb 0.25
}
}
pigment { color rgb 0.5 }
}
warp { repeat 2*x }
warp { repeat 2*y }
scale 0.025
}
}
cylinder { // ground
-60*y, -30*y, 100
pigment { checker color rgb <0, 0, 1>, color rgb <0.9, 0.9, 1> scale 5 }
}
union {
cylinder { -2*y, -1.01*y, 19 }
cylinder { -35*y, -1.5*y, 2 }
pigment { color rgb 1 }
}
The result is the picture in the upper right corner.
global_settings section.There are two parameters in this section:
step: defines the size of the simulation step. The bigger it
is, the less steps you'll need to get a result (and therefore the faster the program will run),
but the result will be less precise. Moreover, if this value is too big, the program has a
tendency to run into computation errors and abort. The default is 0.2;
output: the program can output its result as a grid of cylinders,
a mesh or a mesh2 (in this last case, it will add a #version unofficial MegaPov 0.6;
at the beginning of the output file). The output parameter can take one of three
values: cylinders, mesh or mesh2. The default is to output
a mesh2;
viscosity: the higher this value, the more viscous the air. The
default is 0.05;
wind: this vector specifies the wind direction and strength. The
default is no wind;
gravity: specifies the gravity direction and strength.
cloth section.This section defines all the parameters that define the piece of cloth:
x_size and y_size: defines the number of mesh elements
on each side;
dist: defines the size of the mesh elements (therefore your piece
of cloth is x_size*dist wide and y_size*dist long);
strength: defines the elastic strength of the material;
shear: defines the shear resistance of the material. The higher this
value, the harder it is to force the material to shear;
stiffness: defines the stiffness of the material. The higher it is,
the stiffer the material (note that the cloth can only bend at a junction between two mesh elements
and therefore, the bigger dist is, the stiffer the material will appear whatever its
stiffness);
weight: defines the weight of a piece of cloth of size 1x1 (in
distance units);
hnoise and vnoise: when the piece of cloth is
initialized, a small amount of noise can be added to th position of each vertex to prevent the
results from being too regular. Those values define the amount of horizontal and vertical noise
added;
elongation: specify the maximum elongation of the springs
constituting the model: if they stretch less than elongation times their static
length, their behavior is perfectly elastic, if they stretch more some corrections are applied;
position: specify the cloth starting position and size. If it is
omitted, the cloth starts horizontal, centered on the origin and isn't stretched or compressed.
The syntax is: position { origin, dir1, dir2 }. The piece of cloth will be positioned
in a parallelogram between origin, origin+dir1, origin+dir1+dir2
and origin+dir2;
read_file: specify a file from which the starting position of the
cloth will be read. This file needs to be generated with the --raw-file option (see
below). This option supersedes position;
damping: this parameter should take values between 0 and 1. With
a value of 0 you get a perfect dynamic model, while with a value of 1 you'll get the same behavior
as with version 0.2.0. This parameter is different from viscosity in that the effect
of viscosity depends on the wind and the normal of the cloth at any given point,
while damping is only dependent on the speed of the point. This can be thought of
as a way to model energy deperditions;
intersections: can be on/true or
off/false. If true, the simulator will compute
self-intersections. Note that this is very slow. The default is off.
All these are optional, look into sample.cl for
the default values. Most of these values do not depend on the others, so if you want to run tests
in low resolution and then increase x_size and y_size while decreasing
dist you should get pretty much the same results (the only exception is
stiffness).
Unless you specified position or read_file
the piece of cloth starts centered at the origin and horizontal. If you want to change
this, you can transform it after having given all the parameters by adding any number
of translation and rotations (see sample.cl). Note that these transformations
are applied even if you specified a position or read the data from a file!
In addition to these transformations, it is also possible to
attach a point of the cloth to a position. The syntax for this is: attach { u, v, where }
where u and v are the cloth coordinates (if you used the
position keyword, u goes from 0 at orig to 1 at orig+dir1
and v goes from 0 at orig to 1 at orig+dir2), and
where is a vector specifying the position to which the point should be attached
(if you want good results, it should be reasonably near to the position the point would
naturally have at the beginning). Note that any translation or rotation applied after the point
is attached will affect the position where it is attached.
After the cloth definition, you can add any number of cylinders, boxes, spheres and ground planes (although of course having several ground planes doesn't make lot of sense and will only serve to slow down the program). The syntax is similar to that of POVray, except that an additional parameter can be added after the others to specify how smooth the surface of the object is (the higher the parameter, the more friction there will be whe the cloth touches it).
It is also possible to specify a height field object. As in
POVray the object will fill a cube from <0, 0, 0> to
<1, 1, 1>. The syntax is: height_field { tga "filename" TRANSFORMS }
. The available transformations are scale and translate.
Unfortunately, this object doesn't work right yet :-(
As in POVray, you can specify a vector either by giving its
coordinates between angled brackets (eg: <1,2,3>) or as an expression
featuring the constants x, y and z, floating point numbers
and vectors in brackets. However you cannot specify a number and have it expand automatically
(eg: giving 1.0 where a vector is expected will give a parse error). Moreover the
axis system for the input file is not the same as in POV: y and z are
inverted (z is up and y points into the screen). But the output
follows the POVray conventions and is therefore directly usable in POV.
Type cloth --help for help on how to use the program (if you don't specify
input and output files, standard input and output are used):
flash:~/prog/cloth> ./cloth --help cloth 0.2.0 Usage: cloth [OPTIONS]... -h --help Print help and exit -V --version Print version and exit -iSTRING --in-file=STRING Input file -oSTRING --out-file=STRING Output file -sINT --steps=INT Number of simulation steps -rSTRING --raw-output=STRING Output raw data to file