Thursday, January 01, 2009

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/". 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 ( and Java3d ( Then download the 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 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.


  1. Thanks! This will be interesting to look at.

  2. Anonymous15:46

    thanks for sharing this site. there are various kinds of ebooks available from here

  3. Awesome been working on a similar project for generating cities and found your thesis very interesting. This is pretty impressive for only taking 12 weeks. The graph based generation structure wasn't something I'd considered but now has me pretty excited to try something similar.

    1. Cityscape looks awesome - I worked with the guys building the commercial project CityEngine for 3 years, and saw just how deep you can take a project like this (10's of people and years of work).

  4. i'm in awe of the amount of effort ESRI puts into that. so i'm aware that this is definitely an infinitely scoped project. it's helpful for me to have the art in the book as a guide. it keeps me from going off on more "professional" features. instead i'm trying to keep the aesthetic spartan but build something flexible enough to build a range of styles (dense urban, industrial, suburban, and farms). i keep finding huge rabbit holes i could go down, even something "simple" like factoring setbacks into the placement of a building on a lot turns out to be pretty complicated for arbitrarily shaped lots... as i'm sure you know.

    anyway i keep finding myself going back through your blog posts and thesis and they're always both helpful and inspiring. so thank you for putting all your work out there.