Sity source code

[2016: Tom resurrected this page from the Glasgow servers recently. It contains many mistakes and a few dead links!] Sity (docs) was my master's thesis project. It's a procedural city generator:


[edit: a better weighted straight skeleton implementation can be found here]

It does contain a weighted straight skeleton implementation (that's my picture on the wiki page :), the class name is "skeleton/Bones.java". It isn't very fast or robust. It's basically Felkel's method tweaked to produce weighted straight skeletons.

what follows is the overview that I wrote at the time


Sity is an architecture generator that was researched and implemented over 12 weeks as part of my MEng degree quite a long time ago.
Getting Sity

Before you begin you'll need Java 1.5 (http://java.sun.com) and Java3d (http://java.sun.com/products/java-media/3D/). Then download the sity.zip file (~3MB), extract the contents to a directory.

Running Sity

You can then execute sity with the following command from within the directory:

java -Djava.library.path=./lib/-jar sity.jar -port 2424

If you experience the Java error "java.lang.OutOfMemoryError", you can assign a larger quantity by adding the following argument to the above command.

-Xmx [memory size in bytes]

(for example -Xmx 1G to assign a gigabyte of memory)

If you get the error Exception in thread "main" java.lang.NoClassDefFoundError: javax/vecmath/Matrix4d..., you have forgotten to install Java3d (see above), or maybe need to specify its location in the Java classpath.

It may look different depending on your operating system.

This window remains open as long as Sity at any time via the usual operating system methods, or by pressing the Q key.


Click the "Show preview" to get started...

After clicking in this window you can navigate the city using the arrow keys and AD to slide left and right and WS to move forwards and backwards.

From the preview window you can ask for the current city to be sent to Maya by pressing the return key, and can generate a different city by pressing the space bar. More details about these event to follow.

Returning to the utility window clicking the "Show waterfalls" will display the waterfall graph:

This structure determines how the output city appears.

The waterfall has the following elements:

The controls in the waterfall view are

  • Click and drag on the black background, move around the view
  • Scroll in or out with the mouse, zoom the view
  • The R key will attempt to automatically lay out the waterfalls
  • Click on a waterfall or input plug to select it (note that the utility panel displays the options relevant to the waterfall)
  • Click and drag from an output plug to an input plug to create a new link
  • Click and drag from an output plug to a blank space to create a new waterfall, you will be presented with a menu of compatible waterfalls

  • Click on an output plug to adjust to probabilities of the downstream waterfall:

Each of the sliders controls the probability of each of the downstream waterfalls. By hovering the mouse pointer over the sliders, the tool tips will inform you of what each connection leads
too, at the same time that flow will become highlighted. To remove a flow click the cross (x) button at the under the sliders. To adjust the probability of the downstream waterfall, move the slider up or down. The higher a slider the more likely the waterfall is to be chosen.

By connecting up different waterfalls in different ways a variety of cities can be created. Another way of changing the appearance is through the parameters that appear in the utility window when you click on a waterfall. A description of the waterfalls and the parameters appears at the end of this appendix.

Outputting a City via MEL

As describe above, pressing the return key in the preview window will attempt to output the current sity to Maya via MEL over the local port 2424. However Maya must first be told to listen to that port. To do this open Maya, and in the MEL command box enter

commandPort -rnc -eo -n ":2424";

Once you are finished, the port should be closed again as Maya does not check who is writing to that port and poses a security risk. Close the port using:

commandPort -cl -n ":2424";

Once the port is open, upon pushing return in the preview window the data is sent to Maya, the Maya will flicker and may stop responding during this time. Once this has stopped, the city will have been transferred to Maya.

Outputting a city as an .obj file

It is also possible to output a city a city as a .obj format file, this may be faster, produce the same result and produce less vertices that the MEL method above. Click the "Dump to .obj file" option on the utility panel. You can then open the city in a range of 3D packages.

Saving and loading a set of waterfalls

The save and load buttons will save and load the tree of waterfalls to disk. Note that only those connected to the root node are saved and recovered.

About the Waterfalls

When asked to make a city, Sity may return and create that element again, at that time it may take a different route if there is more than one waterfall connected to the downstream plug. The probability of which waterfall is chosen is set by clicking on the output plug (explained above). You can change the way a waterfall acts by changing its parameters. Often these contain several choices for one variable, such as block width:

The mean specifies the most likely value (approximately meters like all values in sity) and the SD or standard deviation specified how far from this number the value may be. So for many different, chaotically sized blocks you would set the SD to the same value as the mean. For all waterfalls to have the mean value set the SD to zero. The values are truncated to be in
the limit specified (here a 1m to 1000m output range), to ensure there are no invalid sizes. You cannot change these ranges.

Source code details

Source is in a very rough state, use at your own peril. Released under the WTFPL license. It needs the Java3D and jMonkey libraries, which can be found in the sity.zip file (above).

The weighted straight skeleton code can be found in src/skeleton/Bones [edit: much better WSS code can be found here]. Sorry the docs aren't in better condition, it was a race against time to get this out at all.