City Generator Include File

for Persistence of Vision 3.1

Created by Chris Colefax, 1 February 1999

Contents

Installation

The City Generator Include File actually consists of a number of files: the include file itself, City.inc, and the default city macro and object files (City.mcr, Default.obj, Vehicles.obj, Offices.obj, Hotels.obj, and Flats.obj). In order to create your own cities using these default files, you should copy all seven files to one of the directories (folders) in your POV-Ray library path. Normally, this is the INCLUDE subdirectory of the directory you installed POV-Ray in, eg. (on a Windows 9x system):

C:\Program Files\POV-Ray for Windows v3.1\Include

If you don't want to install the files directly in POV-Ray's directories, you can create a separate directory in which to install the files. In this case, you should add that directory's full drive and path to your main POV-Ray INI file, eg. if you installed the *.MCR files in D:\POVFILES\CITY you would add the following line to POVRAY.INI:

Library_Path=D:\POVFILES\CITY

Note that it is possible to move some or all of the files into a subfolder of one of the folders in your POV-Ray library path. If you choose to do this, you will have to update all the #include "..."statements in the associated include, macro, object, and POV files to point to the correct path, eg: if you installed the city object files into a subfolder of your main include directory called OBJFILES, then:

#include "DEFAULT.OBJ" should be changed to #include "OBJFILES\DEFAULT.OBJ" wherever it occurs, and
#include "HOTELS.OBJ" should be changed to #include "OBJFILES\HOTELS.OBJ", etc.

Quick Start

The City Generator Include File builds cities using a combination of include, macro, and object files to create cities, towns, etc. Each of these files support different options to change the sort of city that is created, and you can design your own macro and/or object files to create entirely new and different cities.

The main include file, City.inc "maps out" the city, and includes options to control the placement of streets and city blocks. The default macro file, City.mcr then builds the city by placing objects to create streets and pavements, traffic, and buildings. These objects are defined in the city object files, which include simple vehicles, street lamps, bus stops, traffic lights, and a selection of office, hotel, and apartment buildings. The buildings are created by stacking single levels on top of each other, so that everything from one-storey lowrises to skyscrapers can be generated.

To create a city using the default macro and object files, you simply declare all the options you want to use, and then include the City.inc file, eg:

#declare traffic_spacing = 4;
#declare traffic_lanes = 2;
#declare city_block_count = <10, 5, 0>;
#include "CITY.INC"

If you want to use custom object files, you must include these before including City.inc, eg:

#include "Future.obj"
#include "HoverVehicles.obj"
#include "CITY.INC"

This would create a city using the buildings and vehicles defined in the two *.OBJ files, rather than the default object files. To use custom macro files, you should use the city_macro_file option.

Note that custom object and macro files may support their own options for changing the city characteristics, and may not necessarily support all of the options used by the default files (listed in the following sections). You should check the documentation that comes with the custom files to be sure of which options are supported.

Options Reference

City Include File Options

The following options are for use with City.inc itself, and will alter the city regardless of any custom macro and object files (see above). The City Generator creates cities in the x-z plane (with the y-axis pointing skywards). The city is constructed from a grid of city blocks (containing the buildings), separated by streets running in the x and z directions. The city is centred on the origin, with the overall size being determined by the various measurements below (see city_corners). The scale used is arbitrary, and will generally be determined by the city object files you use. In the case of the default object files, one unit is approximately equal to one metre.

debug_progress

Declaring this option to true will allow you to view the activities of the City Generator Include File as it creates the city. The information sent to POV-Ray's debug stream includes the overall size of the city (in the x-z plane). This can be very useful when parsing large scenes, or for troubleshooting while you are designing your own custom city macro and/or object files.

city_macro_file

This option sets the name of the file which contains the macros you want City.inc to construct the city with. By default, the City.mcr file is used. Note that you do not have to declare this option if the city macros are defined directly within your POV file (see the example scenes provided with the City Generator).

city_block_count

This option sets the number of city blocks generated, each city block being surrounded by pavements and streets. The option can be declared as a vector, with the x-component setting the number of blocks generated along the x-axis, and the y or z-component setting the number of blocks in the z direction, eg:

#declare city_block_count = <6, 4, 0>;

This creates a city made up of 6 x 4 blocks (for a total of 24 city blocks). You can also set this option to a single integer, which will generate the same number of blocks in both the x and z directions, eg:

#declare city_block_count = 6;

This creates 36 city blocks. The default value for city_block_count is 2 x 2 blocks.

buildings_per_block

This options sets the number of buildings created on each city block. Like the city_block_count option, either a vector or float can be used, eg:

#declare buildings_per_block = 3;

will create nine buildings on each city block (3 in the x direction by 3 in the z direction). The default value for buildings_per_block is 3 x 2 buildings.

street_width

This option sets the width of the streets separating each city block. Note that if the default City.mcr file is used, this value will be overwritten by the traffic settings (which you should use instead of the street_width option). The default value (when City.mcr is not used) is 10 units.

pavement_width

This option sets the width of the pavement surrounding each city block (on all four sides). The default value is 4 units.

building_width

This option sets the width and depth of each building in the city. The default value is 25 units.

building_gap

This option sets the gap between adjacent buildings (ie. the width of the city alley ways). The default value is 2 units.

city_tileable

Normally the entire city is surrounded by streets (around the perimeter of the rectangle that bounds the city). Setting this option to true will stop streets being created along the +x and +z edges of the city, so multiple copies of the city can be tiled together, eg:

#declare city_tileable = true;
#declare CityTile = #include "CITY.INC"

object {CityTile} #declare CitySize = city_corner2 - city_corner1;
object {CityTile translate x*CitySize} object {CityTile translate -x*CitySize} 
object {CityTile translate z*CitySize} object {CityTile translate -z*CitySize}

city_transform

This option sets the transformation you want to be applied to the entire city, eg. to convert the city to a right-handed coordinate system:

#declare city_transform = transform {rotate x*90 scale <-1, 1, 1>}

city_corners

Although not an option you can set, the city_corner1 and city_corner2 vectors will be declared by City.inc when you include it. Both vectors lie in the x-z plane (no height values are included), and they are particularly useful when creating tiled cities (see city_tileable). You can also use the city_corner values to place other objects, light sources, the camera, etc. Note that the value is not affected by any city_transform you may have declared, so you should take this into account if you have transformed the city in any way.

City Macro File Options

The options in this section are for use with City.mcr, the default macro file used by City.inc.

city_seed

This option sets the random seed value used to generate the city, and can be changed to generate different arrangements of vehicles and buildings. The default city_seed is 0, and any positive or negative integer can be used (within POV-Ray's numerical limits).

min_building_height and max_building_height

These options set the minimum and maximum heights (in units) of the buildings created in the city. The default values are half of the building_width, and double the building_width (ie. the buildings are between half and twice as high as they are wide). Normally, the highest buildings are created in the centre of the city, with shorter buildings at the edges (although the building_height_turb option will alter this somewhat).

building_height_falloff

This option controls how the building height changes from the centre of the city to the edges. A value of 1 would indicate a linear falloff so a straight line could be drawn from the top of the high buildings in the middle of the city to the lower buildings at the edges. Higher values give more low buildings than high buildings, while values lower than one give more high buildings than low buildings. The default building_height_falloff is 2

building_height_turb

This option sets the randomness of the building heights. When set to 0, the building heights are controlled only by the building_height_falloff value, giving the city a very regular look. Good values generally range from 0 to 1, and the default building_height_turb is 0.5

pavement_height

This value sets the height of the pavement (in the +y direction, where the streets sit at y = 0). The default pavement_height is 0.15 units.

traffic_spacing

This value controls the minimum distance between vehicles on the city streets. Setting this option to zero stops the macro file from creating vehicles altogether. The default traffic_spacing is 10 units.

traffic_lanes

This option sets the number of lanes of traffic created along the city streets, in one direction (eg. a value of 3 would create six lanes, three in each direction). The default traffic_lanes value is 1.

traffic_width

This value sets the width of one traffic lane. This option is used in combination with the traffic_lanes value to calculate the width of the streets (which overrides any street_width option you may have declared). The default traffic_width value is 3 units (which gives a default street_width of 9 units, allowing for one lane width of curb space).

City Object File Options

The options in this section control the objects defined in the default city object files (see Installation). Other city object files may not necessarily support any or all of these options.

city_night

Setting this option to true turns on the night features of the City Generator default object files, including lit building windows and visible lights on street lamps and traffic.

windows_lit

If city_night is enabled, you can use this option to set the proportion of building windows that are lit. A value of zero indicates that no windows are lit, while a value of 1 indicates that all windows are lit. The default windows_lit value is 0.33 (ie. one-third of the windows are lit).

windows_blend

This option controls the transition between lit and unlit windows. A value of 0 indicates no blending, so that individual windows are either completely lit or not lit at all. A value of 1 indicates that all the windows lie somewhere between the two extremes. The default windows_blend value is 0.25

city_right_hand_drive

If the traffic_spacing option is used to generate vehicles on the city streets, you can set this option to true to make the vehicles drive on the right-hand side of the streets.

max_building_types

As detailed above, you can use custom city object files simply by including them before including City.inc. This option sets the maximum number of building types you can use to generate the city, either by including building object files or by defining buildings directly within your POV file. The default value of 100 means you will probably never have to worry about this option, but you can increase this number if required (or decrease it to save a small amount of memory).

Copyright Information

The City Generator Include File, including CITY.INC, CITY.MCR, all documentation, and associated sample *.OBJ and *.POV files are Copyright 1999 by Chris Colefax. Full permission is granted to the user to modify any or all of the files for his/her own use. If modified versions are to be distributed the user should make clear the modifications that have been made by him/herself.

The City Generator Include File may be bundled with or without other software on CD-ROM collections, Bulletin Board systems and other file archives, providing that all associated files, including documentation and samples, are included. I would also request that persons intending to distribute the City Generator Include File in this manner or otherwise would first contact me to ensure that they are in possession of the latest available version.

Further, no restrictions of any sort are placed on the usage of the include file package, and scene files or images created using the include file package remain entirely the property of the user or users who have created them. I claim no liability or responsibility for damages or loss resulting from usage of the include file, or any part of the include file package.

Contacting the Author

If you wish to contact me with bug reports, bug fixes, criticisms, comments, suggested improvements, questions, etc. you can reach me by email at:

ccolefax@geocities.com

or by regular mail at:

POV-Ray^TM and Persistence of Vision^TM are registered trademarks of the POV-Ray Team^TM