#ifndef GEOMETRYELEMENT_HH
#define GEOMETRYELEMENT_HH
//
// $Id: GeometryElement.hpp,v 1.20 2004/02/27 02:57:35 mikeh Exp $
//
// File: GeometryElement.hh
// Purpose: Base class for D0 geometry description.  
// Created: 28-AUG-1997   John Hobbs
//
// $Revision: 1.20 $
//

// Include files
#include <list>
#include <iostream>   // or <iosfwd>
#include "d0om/d0_Object.hpp"
class MatrixD;
class SpacePoint; 
#include "geometry_system/components/GeometryXform.hpp"

namespace dgs {

class absGeometryDistortion;

/**  Base class for D0 geometry description.

     Provides partial interface for alignment and for reconstruction.
     Implements global transformations of elements(offset and
     rotation)
          
     Geometry element positioning is accomplished in one of four ways
     depending on the situation:
     \begin{enumerate}
       \item Initial placement on a parent element should be done using
           a shape's(see below) {\bf position\_child\_at} method.
       \item Absolute positioning should be done using {\bf set_position}.
       \item Positioning relative to another element should be done using
            {\bf set\_relative\_position}
       \item Delta positioning with respect to current position (alignment)
            should be done using the {\bf move} method or the {\bf resize()}
            method of the shape(See below).
     \end{enumerate}
     The {\bf set\_position} and {\bf set\_relative\_position} methods have
     corresponding {\bf get_}X methods.

     Specific geometrical shapes (surfaces and solids) are required to
     inherit from GeometryElement, and to provide an augmented
     interface.  Shapes must provide the following methods for
     converting to/from local coordinates:

     \begin{enumerate}
     \item GeometryXform\& local\_to\_global(const SpecificSpacePoint\&);
     \item SpecificSpacePoint\& global\_to\_local(const SpacePoint\& gpt)
     \item GeometryXform\& local\_to\_xform(const 'SpacePointType'\& pt)
     - Make local transformation corresponding to a point on
     an element               
     \item 'SpecificPointType'\& xform\_to\_local(const GeometryXform\&)
     - Undo local\_to\_xform
     \end{enumerate}

     Here SpecificSpacePoint is local point class relevent to the
     particular shape.  For example, if the shape is a cylindrical
     surface, 'SpecificSpacePoint' should be 'CylindricalCoordinate'.
     'local\_to\_xform' and 'xform\_to\_local' should be private methods.

     Specific shapes must also provide a means to resize themselves if
     appropriate, using a member function {\bf bool resize(???)}  with
     an undefined interface.  This member function must insure that
     the global position of dependents which depend on the size is
     updated by resize.  This can be accomplished by using the line
     {\bf child.set\_relative\_position(GeometryXform(),*this)} in 'resize'
     prior to the return statement.  Here GeometryXform is generated
     from a call to either local\_to\_xform or get\_relative\_position

     Finally, specific D0 detector elements must supply an interface
     for converting from native to local coordinates and vice-versa
     using member functions named:
     \begin{enumerate}
     \item SpecificLocalCoordinate native\_to\_local(SpecificNativeCoord.)
     \item SpecificNativeCoordinate local\_to\_native(SpecificLocalCoord.)
     \end{enumerate}
          
     and must proved a definition of {\bf const
     std::list<GeometryElement*> get\_children() const}. This provides a
     list of the children directly supported by the given element.

*/

class GeometryElement: public d0_Object
{
public:

  ///  Default constructor.
  GeometryElement(): _distortion(0), _rvers(_cvers) {}

  ///  Default destructor.
  ~GeometryElement();

  /**  Define the alignment interface.  

       Relative move specified in local coordinates

  */
  virtual bool move(const GeometryXform& corrected_origin);

  /**  Required interface to return children on given element.
 
       Return a list of all children of this surface.  Children are
       defined to be those elements at the next level in the
       hierarchy.  {\em This virtual member must be provided when the
       specific detector element is defined.}

       This should be overridden only if an element's local coordinate
       is not identical to the base surface coordinate.  This is 
       needed for SMT ladders.

    */
  virtual const std::list<GeometryElement*> get_children() =0;

  /**  Access global geometry transform.

       Return the transformation describing the position of the origin
       of this element and the rotation matrix describing the
       orientation of its x--, y-- and z--axes with respect to the
       global D\O\ coordinate system.

  */

  const GeometryXform& get_positionptr() const { return _global_position; } 

  GeometryXform get_position() const { return _global_position; } 

  /**  Set position.  

       Set the position of the geometry object to origin.   Initial positioning
       on a parent surface should be done using {\bf position\_child\_at()}
       methods of the parent {\bf shape} class (e.g., Box, Plane, ...)

  */
  bool set_position(const GeometryXform& origin);

  /**  Get position/orientation relative to the provided transformation.
       
       This is a convenience method.    The call:

             {\bf C = BE.get\_relative\_position(A);}

       is identical to:

              B = BE.get_position();
	      C = B.diff(A);

   */
  GeometryXform get_relative_position(const GeometryXform& relative_to_this) const;  

  /**  Set position/orientation relative to the provided transformation.

       This is a convenience method.    The call:

             {\bf BE.set\_relative\_position(B,A);}

       is identical to:

              C = B.apply(A);
	      BE.set_position(C);

   */
  bool set_relative_position(const GeometryXform& relative_to_this,
			     const GeometryXform& origin);  

  ///  Set distortion.
  bool set_distortion(const absGeometryDistortion* distortion);

  ///  Access distortion.
  absGeometryDistortion* get_distortion() const;

  ///  Stream insertion operator.
  friend std::ostream& operator<< (std::ostream& os, const GeometryElement& me);


protected: // These routines support functions required by specific shapes

  /**  Convert local point to global point.

       This {\em protected} member is called by the {\bf
       local\_to\_global} members of the concrete shapes below.

  */
  SpacePoint local_to_global(const SpacePoint &lpt) const;
  
  /**  Convert global point to local point.
       
       This {\em protected} member is called by the {\bf
       global\_to\_local} members of the concrete shapes below.
       
  */
  SpacePoint global_to_local(const SpacePoint &gpt) const;

  /** Convert a 3x3 matrix from local to global coordinates.

       This {\em protected} member is called by the {\bf
       local\_to\_global} members of the concrete shapes below.

  */
  MatrixD local_to_global(const MatrixD& errorMatrix) const;

  /** Provide for schema evolution.

      This {\em protected} member is called from the corresponding member 
      of all base clasees which directly inherit from GeometryElement.  The
      code here will handle cases when the schema has evolved since a 
      version being read from disk.  CURRENTLY A NOP.  Here for documentation
      purposes.

  */
  void update_format() {} 

private:

  ///  Absolute position in D0.
  GeometryXform          _global_position;

  ///  Distortion.
  absGeometryDistortion* _distortion;

  /// Persistance version number for linked code
  static int _cvers;  // Currently linked version of code.  Defined in constructors

  /// Persistance version number read (or current if not read)
  int _rvers;

public:

  D0_OBJECT_SETUP(GeometryElement);

};

// Just the declarations, sir
std::ostream& operator<< (std::ostream& os, const GeometryElement& me);

}
#endif // GEOMETRYELEMENT_HH