The detector geometry is represented by a hierarchical tree in which each subdetector is composed of a tree of elements representing logical layers in the detector. The top of the tree for each subdetector is a reference point to which all positions within the subdetector are tied. The depth of the tree depends on the subdetector complexity.

A generic geometry system provides geometrical shapes from which the subdetector elements derive. The shape interfaces allow the tree structure to be supported in a consistent manner so that if (e.g.) the detector is repositioned as a result of in situ alignment, the change can be applied to the reference point of the detector and the rest of the elements in the tree will be automatically repositioned. This is true for repositioning starting at any element in the tree, not just the top.

The base geometry defined using the generic elements will typically have no material or calibration information. It will be used to

1. define the detector structure,
2. provide an interface to move and resize surfaces,
3. provide a means to save and retrieve the geometry structure,
4. allow users to traverse the hierarchy using a subdetector specific addressing scheme and
5. provide a means to convert positions on elements of the tree into the equivalent position in a global DO reference frame.

Information needed to provide additional functionality such as material distribution and calibration will be defined and described elsewhere and is expected to use the base geometry for absolute position information.

The general system is designed to provide those functions described in the previous paragraph. However, most users of the geometry system do not need to see the entire tree or will wish to have the information recast into a more direct form. Also, except for the purposes of alignment, users do not need to reposition detector elements. For example, users of the silicon geometry are mainly interested in the position of a detector ladder or wedge. They generally do not care about the positions of the intermediate barrels, layers, and disks to which the ladders and wedges are mounted. Users of the silicon geometry also expect to be given the correctly aligned geometry. For these reasons, each subdetector will provide a detector specific interface to the geometry as outlined below. Users will not directly access the geometry hierarchy but instead get information through this interface class.

Geometrical Shapes and Transformations

The geometry system provides the low level classes to be used to develop specific detector geometries. These classes include local and global coordinate systems, geometrical transformations (translations and rotations), and a set of basic, rigid body shapes (ie. planes, cylinders, etc.). In addition, the system supports the construction of complicated geometries by building up a hierarchical collection of basic shapes. Finally, the system includes the ability to modify the geometry (via move and resize), in order to support detector alignment.

To implement a specific detector geometry, the basic geometrical shapes needed to describe the detector (logical) support surfaces should be identified. Implementations of these detector surfaces need to be written, inheriting from the shapes included in the Geometry System. These implementations must specify the associations between the various surfaces describing the detector hierarchy by building a ``tree'' of surfaces. This is done by associating ``child'' surfaces with ``parent'' surfaces via the parent member function get_children. By linking the surfaces together with get_children, the Geometry System is able to automatically propagate moving and resizing throughout the entire detector tree.

Coordinate Systems

There are two types of coordinate systems supported in the Geometry System - global and local. There is one global coordinate system in the experiment, and positions in this coordinate system are represented by instances of the class GlobalPoint. Local coordinate systems are used to specify points on individual detector surfaces and are represented by the abstract class LocalPoint. Specific implementations of local points are CartesianCoordinate, CylindricalCoordinate and SphericalCoordinate. Units are assumed throughout to be cm and radians.

Geometry Tree and Subdetector Interface

The basic top--level structures of the geometry tree consist of a class BaseGeometry representing the entire detector and classes xBaseGeometry, with x=Si, Cft, Cal, Muon for each of the subdetectors.

The parent/child relationship of the top two levels of the hierarchy is maintained using the d0_Ref pointer class. This is done because d0_Ref implements delayed loading of objects. This means that data pointed to by a d0_Ref is not instantiated until the pointer is actually dereferenced, thereby minimizing the CPU (and generally I/O) needed. When implementing classes deeper in the hierarchy, designers should use d0_Ref if further delayed loading is useful.

The interface to BaseGeometry is rather trivial. It supports creating an empty detector, creating a detector pointing to given instances of the four subdetectors and access to each of the subdetector geometries in both constant and non-constant forms. No mechanism is provided for replacing individual subdetectors on--the--fly. This implies that once constructed, the geometry structure is fixed. The positions of elements can be adjusted using the alignment interface of the shapes from which they inherit, but the basic layout remains intact. Changing from one geometry to another at run time, as is needed when the reconstruction program crosses a run boundary corresponding to a detector being moved, will be handled automatically by the Geometer (see below).

The minimal interface to the xBaseGeometry classes is also simple. It consists of constructors relevant to the specific subdetector, the interface inherited from (e.g.) ReferencePoint and the ``virtual constructor'' build_default(RCP* RCPinit). A consequence of using d\O om for I/O is that default constructors must not imply instantiation of attributes via explicit calls to new of attributes. This implies that children in the hierarchy cannot be dynamically allocated in the default constructor of the parent without creating the possibility of memory leaks. To avoid this, the ``virtual constructor'' build_default() is provided. It is designed to build the default geometry or the geometry specified via an RCP argument. Thus the initial run II base geometry will be instantiated using the following code fragment:

     d0_Ref<BaseGeometry> BaseGeometry::build_default() {
        d0_Ref<SiBaseGeometry> = SiBaseGeometry::build_default();
        d0_Ref<SftBaseGeometry> = SftBaseGeometry::build_default();
        d0_Ref<CalBaseGeometry> = CalBaseGeometry::build_default();
        d0_Ref<MuonBaseGeometry> = MuonBaseGeometry::build_default();
     }

The build_default() method does not have to arbitrarily complicated -- it is intended to instantiate only the ideal geometry of each subdetector. As such the RCP used to drive it (not shown) will be generally relatively simple.

It is expected that this minimal interface will be supplemented with const and non-const accessors to retrieve the children immediately below the top level for each subdetector, a print method overloading stream insertion and any other methods users need. However, no caching of derived information nor direct access to children deeper than one level should be part of this interface. Functions like these should be implemented in the xGeometer class described below.

Geometry Management and User Access

Access to a defined (constant) geometry requires two components: (1) a manager class which insures that the correct geometry has been instantiated and (2) an interface class for each subdetector through which users access the geometry. This section describes the manager class GeometryManager, the subdetector user-interface class xGeometer and support classes which minimize the coupling between these two.

Geometry Management: The GeometryManager

The current geometry is maintained by the GeometryManager class. This is a singleton which is instantiated with the instructions necessary to maintain the proper current geometry. These may allow selecting the current geometry from a given set based on user input, primarily expected to be run number. To achieve this, the GeometryManager is notified via the member function check_geometry() whenever a new geometry might be needed. During production processing, this notification will occur once per event. The manager decides whether a new geometry is actually needed. If it is, the geometry is loaded into memory and a message is sent to the user interface class xGeometry for each known subdetector. The message includes the address of the new geometry for that particular subdetector.

The interface for the GeometryManager is rather simple. There are three versions of a ``virtual constructor'', a member to return the instance of the class and a member used to ask the manager to check if a new geometry is needed.

The user interface: xGeometer

To keep users from needing to access the geometry tree directly, and additionally to decouple the geometry tree from users code, it is expected that each subdetector has an interface class through which users access the geometry information. The generic term for this class is xGeometer and each subdetector needs to provide such a class.\footnote{For each subdetector, ``x'' is replaced by a name identifying the subdetector. For example the xGeometer implementation for the silicon detector is called SiGeometer.} The geometer receives a message from the geometry manager whenever the current geometry changes, and it is expected that subdetector caches and short-cut addressing to detector elements deep in the geometry tree will be provided by the geometers if needed. The geometers are expected to be singletons and are not persistent.

The simple design described in the previous paragraphs has two significant shortcomings. First, the implementation of the GeometryManager class must explicitly include the header of each of the subdetector geometers in order to send the refresh message (from GeometryManager::check_geometry()). Second, the set of subdetector geometers to be notified is unspecified. To address these problems, two additional classed are defined. The first is the abstract geometry messenger class absGeometryMessenger, and the second is a geometer decoupler class denoted XGeometerDecoupler.

A concrete instance of the abstract class absGeometryMessenger class implements a member function whose purpose is to send the refresh message to each of the desired xGeometers. The required messenger(s) is(are) passed to the GeometryManager when it is instantiated. The interface to the messengers is trivial. There is a single member, notify_subdetectors which is called by the GeometryManager when a new geometry is loaded. This then calls the protected virtual member absGeometryMessenger::refresh(d0_Ref$<$BaseGeometry$>$). The refresh member is responsible for calling each of the required subdetector xGeometer::refresh members. For production running, there is only one concrete messenger, FixedGeometryMessenger. We expect that in test environments, a simple messenger specific to the given subdetector will be used. Although both of these cases require only a single messenger, in general, a given messenger can hold a pointer to another messenger, creating a chain of messengers. Each member of the chain is called when a new geometry is loaded.

The absGeometryMessenger class eliminates the problem of having the set of subdetector xGeometers to be notified when the geometry changes hardwired into the GeometryManager. However, the xGeometer xGeometer headers must still be included in the messenger implementation files. This problem is avoided by defining a decoupler for each of the the xGeometers. The decoupler class has only a refresh method so its interface is simple and stable. The refresh method of the decoupler simply calls the refresh method of the true geometer. Thus, the header for the true xGeometer is not required except in the implementation file of the decoupler. By convention, the decoupler class named xGeometerDecoupler is matched with the subdetector geometer named xGeometer.

Auxiliary Support: a Handle class

In addition to caches or fast addressing in the xGeometer implementations, a means is provided to return an indirect pointer to a given detector geometry element via the templated Handle$<$T$>$ class. In addition to providing an indirect pointer, the Handle can be made to point to the same point in the geometry tree\footnote{For example, the first ladder in the third layer of the fourth silicon barrel} even if the underlying geometry is changed.\footnote{For example, if a run boundary implies a different alignment, the Handle will point to the new geometry but to the same point in the tree as previously.} This is done by using an associated HandleCache$<$T$>$ class within the xGeometer. When the geometer is notified that a new geometry is present, the cache is used to update all handles pointing within the tree. An example of using handles and maintaining a handle cache is given in the class SiGeometer in the package silicon_geometry.