Database Structure

HyperCities uses about 30 tables; this section provides a brief introduction to them. An ER diagram of the database is also included in the /install directory of the installation package.

Tables

access_rights, map_states, marker_styles, object_states, object_types, tile_types, and user_states store configuration parameters. These are subject to change in future releases; we are planning to add a few new object_types in the next release.

Here is a summary of the meaning of each property:

access_rights

The actions a user is allowed to perform on an action. These work like UNIX file permissions.

• 7: User may view, edit, or delete the object.
• 5: User may view and delete but not edit the object. (Rare)
• 3: User may view or edit but not delete the object.
• 2: User may edit but not view the object. (Rare)
• 1: User may view but not edit or delete the object.
• 0: User may not view, edit, or delete the object.

map_states -- These states represent a user's permissions with regard to a map. These are much less fine-grained than with objects and are in fact rarely used in the current version, because adding a map requires editing the database.

• 1: Public. Anyone may view the map.
• 2: Private. No one may view the map.
• 3: Pending. Unused.
• 4: Testing. Unused.

marker_styles

What type of style an object has on the map.

• 0: Empty (no representation on the map)
• 1: Point (A single point)
• 2: Line
• 3: Polygon
• 4: 3D Point
• 5: 3D Line
• 6: 3D Polygon

object_states

Permissions for regarding collections and objects for all users. A permission level for each collection is specified using one of these values, but access for individual users may be designated using the objects_states table.

• 1: public. Any user may view this collection, and any user may add to it.
• 2: protected. Any user may view this collection, but only users with a password may add to it.
• 3: private. This collection is not visible to the public.
• 4: inappropriate. This collection has been flagged as inappropriate by an administrator and is no longer visible to the public. Unused.
• 5: deleted. This collection has been marked as deleted and no longer shows up in collections. Generally, objects are not deleted. Their object_state_id is simply set to 5, which prevents them from showing up in queries.

object_types

The type of each object, which differentiates plain objects from collections, for example.

• 1: dummy. Unused.
• 2: collection. A group of any kind of items, including other collections.
• 3: 2D item. A placemark, line, or polygon on the map created in Maps mode.
• 4: 2D NetworkLink. A link to a remote KML file, which has only 2D content.
• 5: 3D object. A placemark, line, or polygon created in Earth Mode.
• 6: 3D NetworkLink. A link to a remote KML file, which has 3D content.
• 7: Scene. A Rich Object; reserved for implementation in a future release of HyperCities.
• 8: External Data Source. A collection stored remotely. Reserved for implementation in a future release of HyperCities.
• 9: Collection managed externally. Internally used to denote a collection whose access rights are managed by another server.

tile_types

Which graphics library was used to render the map tiles, either GraphicsMagick(1) or MapCruncher (2).

user_states

What state a user's account is in.

• 1: Pending. Useful if you enable your own registration process, but not used by OpenID.
• 2: Disabled. User no longer allowed to login.
• 10: Activated. User has registered to use HyperCities.
• 11: Administrator. User is administrator.

Resources and tables

For more information about data types, please refer to the database schema. The following is a brief overview of the functions each table serves.

Cities are stored in the cities table.

Rich Objects and Collections

The state of an object (a marker, line, or shape on the map) is stored across several tables:

• objects contains general metadata about the object. Both collections and objects are stored here. An object's owner is stored in objects.owner_id.
• contents stores the content associated with the object; each object may have one content item, defined in objects.content_id, but not all objects have one content item.
• object_mappings stores the location(s) in time and space of each object, as well as information for displaying it on the map such as the marker style and KML code to create the object on Google maps. An object may have many mappings, but most will only have one.
• object_relations defines relationships between collections and their child objects and collections. object_id denotes the parent, and subject_id denotes the child. An object can have many object_relations, both as parents and as children. In other words, an object can be in many collections. The collection hierarchy can be of infinite depth, but circular references (e.g. a collection that contains a second collection that contains the first collection) are not allowed.

objects_users stores auxiliary permissions granted by an objects owner to other users.

Maps

Map data is stored across the following tables; map tiles themselves are generally served remotely. These tables will be pre-populated with the maps that HyperCities uses, which can be safely removed.

• maps contains general metadata about each map. This contains positional and temporal data as well; there is no maps_mappings table. Maps are also linked to cities in maps.city_id. If you do wish to use the included maps, you must also retain the corresponding city.
• maps_profiles contains other data related to displaying the map in Google Maps, including the URL where map tiles are stored, as well as minimum and maximum zoom levels.
• maps_tags, maps_users, and maps_legends are generally not used.

Users

User data is split between users and users_openids. users contains data acquired via the registration form, while users_openids links these to the Open Ids used to log in. users_openids data is used only for logging in.

Other tables

search_atoms and search_hits index results found with the search engine. tags, object_tags, and map_tags are intended for tagging, a feature which has not yet been implemented.

Please note that one stored procedure, dateLarger, is also used and will be created by the script.