CityGen V0.8

Detailed Construction file structure


Introduction
This file describe the details of construction file. It only covers the structure of the construction file and not basic XML. For further reading on XML refer to here and here. It is also highly recommended to review the example configuration files example1_cfg.xml and example2_cfg.xml.

Jump to the root node.

Index

Elements  Simple types 
Building  tFloatRange 
Call  tProbability 
Choose  tUINTRange 
CityGen  tVrmlTag 
DrawBox 
DrawFloor 
DrawPyramid 
GoUp 
Maybe 
Pop 
Procedure 
Push 
Rotate 
ScaleTo 
Street 
Texture 
TextureGroup 


Detailed listing

element Building

diagram
type extension of OperationSequence
children DrawFloor DrawBox DrawPyramid GoUp Rotate ScaleTo Call Choose Maybe Push Pop
used by
element CityGen
attributes
Name  Type  Use  Default  Fixed  Annotation
probability  tProbability  optional  1.0    
documentation 
Non-normalized probability of choosing this buildings. See tProbability.
vrmlTag  tVrmlTag  optional      
documentation 
DEF VRML 2.0 tag string.
See tVrmlTag.
annotation
documentation 
Building construction template definition.

element Call
diagram
used by
group Operation
attributes
Name  Type  Use  Default  Fixed  Annotation
name  xs:string  required      
documentation 
Name of procedure to call.
repeat  tUINTRange  optional  1    
documentation 
Number of times to repeat calling the procedure. Either a fixed positive integer 
value or a positive integer range for which to pick uniformly.
annotation
documentation 
Call a procedure.

element Choose
diagram
children ChooseOption
used by
group Operation
annotation
documentation 
Randomly choose a single operation sequence to perform.

element Choose/ChooseOption
diagram
type extension of OperationSequence
children DrawFloor DrawBox DrawPyramid GoUp Rotate ScaleTo Call Choose Maybe Push Pop
attributes
Name  Type  Use  Default  Fixed  Annotation
probability  tProbability  optional  1.0    
documentation 
Non-normalized probability for this choose option.
annotation
documentation 
A possible option for choose.

element CityGen
diagram
children Building Street Procedure TextureGroup
attributes
Name  Type  Use  Default  Fixed  Annotation
numCellsX  xs:unsignedInt  required      
documentation 
City size (in cells) in the X direction
numCellsY  xs:unsignedInt  required      
documentation 
City size (in cells) in the Y direction
streetEveryX  xs:unsignedInt  optional  0    
documentation 
Number of city cells in the X direction between streets.
A value of 0 indicates no streets.
streetEveryY  xs:unsignedInt  optional  0    
documentation 
Number of city cells in the Y direction between streets.
A value of 0 indicates no streets.
cellSizeX  xs:float  required      
documentation 
Size of a city cell in the X direction.
cellSizeY  xs:float  required      
documentation 
Size of a city cell in the Y direction.
randomSeed  xs:string  optional      
documentation 
Initial value for the random seed in hex prefixed by "0x" (e.g., 0x1F).
Fixing this value enables recreation of a particular city
and is an efficient way to store and share big cities.
annotation
documentation 
Root element a CityGen construction file.

element DrawBox
diagram
type extension of TexturedDraw
children Texture
used by
group Operation
attributes
Name  Type  Use  Default  Fixed  Annotation
useLastTexture  xs:boolean  optional  false    
documentation 
If set to "true" then the last texture is used. This is useful if you want to draw
a single object using the same random texture. The first draw operation
picks the texture at random and the remaining draw operations set this attribute to "true".
useTextureGroup  xs:string  optional      
documentation 
Setting this attribute specified the texture group from which to randomly pick
a texture. Notice that instead you can define an anonymous texture (see
example configuration files).
noColor  xs:boolean  optional  false    
documentation 
Set to "true" to indicate that this draw operation does not have a color.
This is useful if you are using a colored texture.
height  tFloatRange  required      
documentation 
The height of this box either as a constant or an interval from which to
pick the height uniformly.
closed  xs:string  optional  no    
documentation 
Specifies if this box is closed.
annotation
documentation 
Draws a box (either open 4 walls, partially closed or closed).

element DrawFloor
diagram
type extension of TexturedDraw
children Texture
used by
group Operation
attributes
Name  Type  Use  Default  Fixed  Annotation
useLastTexture  xs:boolean  optional  false    
documentation 
If set to "true" then the last texture is used. This is useful if you want to draw
a single object using the same random texture. The first draw operation
picks the texture at random and the remaining draw operations set this attribute to "true".
useTextureGroup  xs:string  optional      
documentation 
Setting this attribute specified the texture group from which to randomly pick
a texture. Notice that instead you can define an anonymous texture (see
example configuration files).
noColor  xs:boolean  optional  false    
documentation 
Set to "true" to indicate that this draw operation does not have a color.
This is useful if you are using a colored texture.
pointingDown  xs:boolean  optional  false    
documentation 
Set to "true" to indicate that this floor rectangle has a pointing down normal. 
Default is a pointing up normal.
annotation
documentation 
Draws a floor rectangle.

element DrawPyramid
diagram
type extension of TexturedDraw
children Texture
used by
group Operation
attributes
Name  Type  Use  Default  Fixed  Annotation
useLastTexture  xs:boolean  optional  false    
documentation 
If set to "true" then the last texture is used. This is useful if you want to draw
a single object using the same random texture. The first draw operation
picks the texture at random and the remaining draw operations set this attribute to "true".
useTextureGroup  xs:string  optional      
documentation 
Setting this attribute specified the texture group from which to randomly pick
a texture. Notice that instead you can define an anonymous texture (see
example configuration files).
noColor  xs:boolean  optional  false    
documentation 
Set to "true" to indicate that this draw operation does not have a color.
This is useful if you are using a colored texture.
height  tFloatRange  required      
documentation 
The height of this pyramid either as a constant or an interval from which to
pick the height uniformly.
annotation
documentation 
Draws a pyramid

element GoUp
diagram
used by
group Operation
attributes
Name  Type  Use  Default  Fixed  Annotation
height  tFloatRange  required      
documentation 
The height to go up either as a constant or an interval from which to pick
the height uniformly.
annotation
documentation 
Goes up without drawing anything

element Maybe
diagram
type extension of OperationSequence
children DrawFloor DrawBox DrawPyramid GoUp Rotate ScaleTo Call Choose Maybe Push Pop
used by
group Operation
attributes
Name  Type  Use  Default  Fixed  Annotation
probability  xs:float  optional  0.5    
documentation 
Probability (between 0.0-1.0) of performing the operation sequence inside this
maybe element.
annotation
documentation 
Maybe perform this operation sequence.

element Pop
diagram
used by
group Operation
attributes
Name  Type  Use  Default  Fixed  Annotation
popCellVertices  xs:boolean  optional  true    
documentation 
Whether or not to pop the current cell size and orientation. Good for restoring 
after calls to ScaleTo or Rotate.
popHeight  xs:boolean  optional  true    
documentation 
Whether or not to restore the saved height.
popRandomSeed  xs:boolean  optional  true    
documentation 
Whether or not to restore the random seed. If the random seed is restored all 
random results are the same - this is very useful in some cases.
annotation
documentation 
Restores the current parameters - used with push

element Procedure
diagram
type extension of OperationSequence
children DrawFloor DrawBox DrawPyramid GoUp Rotate ScaleTo Call Choose Maybe Push Pop
used by
element CityGen
attributes
Name  Type  Use  Default  Fixed  Annotation
name  xs:string  required      
documentation 
Name of this procedure.
annotation
documentation 
A named procedure that contains building operations.

element Push
diagram
used by
group Operation
attributes
Name  Type  Use  Default  Fixed  Annotation
count  xs:unsignedInt  optional  1    
documentation 
No of times to repeat the push.
annotation
documentation 
Saves the current parameters -used with pop

element Rotate
diagram
used by
group Operation
attributes
Name  Type  Use  Default  Fixed  Annotation
theta  tFloatRange  required      
documentation 
The rotation angle in degrees either as a constant or an interval from which to 
pick the angle randomly.
distance  tFloatRange  required      
documentation 
A distance of the lower left corner angle in degrees from its original 
position either as a constant or an interval from which to pick the distance
uniformly.
annotation
documentation 
Rotate while not exiting the current cell.
This is useful for creating non axis-aligned buildings.

element ScaleTo
diagram
used by
group Operation
attributes
Name  Type  Use  Default  Fixed  Annotation
where  xs:string  required      
documentation 
Scale to this point. Use "center" to shrink the cell or "v0"-"v3" to scale to 
either edges.
scalex  tFloatRange  required      
documentation 
Amount to scale in the X direction (either a float or a float interval).
scaley  tFloatRange  required      
documentation 
Amount to scale in the Y direction (either a float or a float interval).
scaleType  xs:string  optional  relative    
documentation 
How to interpret the scales - either relative as percentage of the current 
value or exact size to scale to.
annotation
documentation 
Scales the viewcell to the specified location.

element Street
diagram
type extension of OperationSequence
children DrawFloor DrawBox DrawPyramid GoUp Rotate ScaleTo Call Choose Maybe Push Pop
used by
element CityGen
attributes
Name  Type  Use  Default  Fixed  Annotation
probability  tProbability  optional  1.0    
documentation 
Non-normalized probability of choosing this street.
See tProbability.
type  xs:string  required      
documentation 
Type of street that is being defined here.
annotation
documentation 
Street construction template definiting.

element Texture
diagram
used by
element TextureGroup
complexType TexturedDraw
attributes
Name  Type  Use  Default  Fixed  Annotation
imageURL  xs:anyURI  required      
documentation 
The image file name. Either a local file or a remote file
(e.g., http://something/img.jpg).
Notice that some VRML players allow only grayscale textures to be mixed with 
color.
probability  xs:float  optional  1.0    
documentation 
Non-normalized probability of choosing this texture. See tProbability.
scalex  xs:float  optional  1.0    
documentation 
Controls how often is the texture repeated horizontally.
scaley  xs:float  optional  1.0    
documentation 
Controls how often is the texture repeated vertically.
relativeToWidth  xs:boolean  optional  true    
documentation 
Whether scaling is relative to the cell width. This is useful for making textures
repeat more for tall buildings.
relativeToHeight  xs:boolean  optional  true    
documentation 
Whether scaling is relative to the cell height. This is useful for making textures
repeat more for tall buildings.
annotation
documentation 
A texture definition.

element TextureGroup
diagram
children Texture
used by
element CityGen
attributes
Name  Type  Use  Default  Fixed  Annotation
name  xs:string  required      
documentation 
Name of this texture group.
annotation
documentation 
A named group of textures.

simpleType tFloatRange
type restriction of xs:string
used by
attributes Rotate/@distance DrawBox/@height DrawPyramid/@height GoUp/@height ScaleTo/@scalex ScaleTo/@scaley Rotate/@theta
annotation
documentation 
A float or an interval of floats. Float intervals are specified as "[min,max]" and
are inclusive.

simpleType tProbability
type restriction of xs:float
used by
attributes Building/@probability Street/@probability Choose/ChooseOption/@probability
facets
minInclusive 0.0
annotation
documentation 
Probability to be chosen with respect to the other elements (non-normalized). This means that the actual run-time probability is
normalized over the sum of probabilities of all other available elements.

For example:
A city with two building types, type 'T' with probability set to 1.0 and type 'H'  with probability set to 3.0.
Then the run-time probability for type 'T' is 1/(1+3)=25% versus 75% for type 'H'.

simpleType tUINTRange
type restriction of xs:string
used by
attribute Call/@repeat
annotation
documentation 
A positive integer or an interval of positive integers. Positive integer intervals
are specified as "[min,max]".

simpleType tVrmlTag
type restriction of xs:string
used by
attribute Building/@vrmlTag
annotation
documentation 
Special user define DEF tag to be inserted into the VRML 2.0 output file. 
Currently vrmlTag support alpha-numeric strings, some VRML 2.0 allowed 
symbols and '%x' and '%y' macros for specifying the current cell coordinates.