Class Surface

Inheritance Relationships

Base Types

Derived Types

Class Documentation

class Acts::Surface : public virtual Acts::GeometryObject, public std::enable_shared_from_this<Surface>

Abstract Base Class for tracking surfaces.

The Surface class builds the core of the Acts Tracking Geometry. All other geometrical objects are either extending the surface or are built from it.

Surfaces are either owned by Detector elements or the Tracking Geometry, in which case they are not copied within the data model objects.

Subclassed by Acts::ConeSurface, Acts::CylinderSurface, Acts::DiscSurface, Acts::LineSurface, Acts::PlaneSurface

Public Types

enum SurfaceType

This enumerator simplifies the persistency & calculations, by saving a dynamic_cast, e.g.

for persistency

Values:

enumerator Cone = 0
enumerator Cylinder = 1
enumerator Disc = 2
enumerator Perigee = 3
enumerator Plane = 4
enumerator Straw = 5
enumerator Curvilinear = 6
enumerator Other = 7

Public Functions

~Surface()
const AlignmentToBoundMatrix alignmentToBoundDerivative(const GeometryContext &gctx, const FreeVector &derivatives, const Vector3D &position, const Vector3D &direction) const

The derivative of bound track parameters w.r.t.

alignment parameters of its reference surface (i.e. local frame origin in global 3D Cartesian coordinates and its rotation represented with extrinsic Euler angles)

Return

Derivative of bound track parameters w.r.t. local frame alignment parameters

Parameters

  • gctx: The current geometry context object, e.g. alignment

  • derivatives: Path length derivatives of the free, nominal parameters to help evaluate change of free track parameters caused by change of alignment parameters

  • position: The position of the paramters in global

  • direction: The direction of the track

const AlignmentRowVector alignmentToPathDerivative(const GeometryContext &gctx, const RotationMatrix3D &rotToLocalZAxis, const Vector3D &position, const Vector3D &direction) const

Calculate the derivative of path length w.r.t.

alignment parameters of the surface (i.e. local frame origin in global 3D Cartesian coordinates and its rotation represented with extrinsic Euler angles)

Re-implementation is needed for surface whose intersection with track is not its local xy plane, e.g. LineSurface, CylinderSurface and ConeSurface

Return

Derivative of path length w.r.t. the alignment parameters

Parameters

  • gctx: The current geometry context object, e.g. alignment

  • rotToLocalZAxis: The derivative of local frame z axis vector w.r.t. its rotation

  • position: The position of the paramters in global

  • direction: The direction of the track

void assignSurfaceMaterial(std::shared_ptr<const ISurfaceMaterial> material)

Assign the surface material description.

The material is usually derived in a complicated way and loaded from a framework given source. As various surfaces may share the same source this is provided by a shared pointer

Parameters

  • material: Material description associated to this surface

const DetectorElementBase *associatedDetectorElement() const

Return method for the associated Detector Element.

Return

plain pointer to the DetectorElement, can be nullptr

const Layer *associatedLayer() const

Return method for the associated Layer in which the surface is embedded.

Return

Layer by plain pointer, can be nullptr

void associateLayer(const Layer &lay)

Set Associated Layer Many surfaces can be associated to a Layer, but it might not be known yet during construction of the layer, this can be set afterwards.

Parameters

  • lay: the assignment Layer by reference

const SurfaceBounds &bounds() const = 0

Return method for SurfaceBounds.

Return

SurfaceBounds by reference

const Vector3D center(const GeometryContext &gctx) const

Return method for the surface center by reference.

Note

the center is always recalculated in order to not keep a cache

Return

center position by value

Parameters

  • gctx: The current geometry context object, e.g. alignment

const BoundRowVector derivativeFactors(const GeometryContext &gctx, const Vector3D &position, const Vector3D &direction, const RotationMatrix3D &rft, const BoundToFreeMatrix &jacobian) const

Calculate the form factors for the derivatives the calculation is identical for all surfaces where the reference frame does not depend on the direction.

Return

a five-dim vector

Parameters

  • gctx: The current geometry context object, e.g. alignment

  • position: is the position of the paramters in global

  • direction: is the direction of the track

  • rft: is the transposed reference frame (avoids recalculation)

  • jacobian: is the transport jacobian

std::shared_ptr<Surface> getSharedPtr()

Retrieve a std::shared_ptr for this surface (non-const version)

Note

Will error if this was not created through the makeShared factory since it needs access to the original reference. In C++14 this is undefined behavior (but most likely implemented as a bad_weak_ptr exception), in C++17 it is defined as that exception.

Note

Only call this if you need shared ownership of this object.

Return

The shared pointer

std::shared_ptr<const Surface> getSharedPtr() const

Retrieve a std::shared_ptr for this surface (const version)

Note

Will error if this was not created through the makeShared factory since it needs access to the original reference. In C++14 this is undefined behavior, but most likely implemented as a bad_weak_ptr exception, in C++17 it is defined as that exception.

Note

Only call this if you need shared ownership of this object.

Return

The shared pointer

bool globalToLocal(const GeometryContext &gctx, const Vector3D &position, const Vector3D &momentum, Vector2D &lposition) const = 0

Global to local transformation Generalized global to local transformation for the surface types.

Since some surface types need the global momentum/direction to resolve sign ambiguity this is also provided

Return

boolean indication if operation was successful (fail means global position was not on surface)

Parameters

  • gctx: The current geometry context object, e.g. alignment

  • position: global 3D position - considered to be on surface but not inside bounds (check is done)

  • momentum: global 3D momentum representation (optionally ignored)

  • lposition: local 2D position to be filled (given by reference for method symmetry)

void initJacobianToGlobal(const GeometryContext &gctx, BoundToFreeMatrix &jacobian, const Vector3D &position, const Vector3D &direction, const BoundVector &pars) const

Initialize the jacobian from local to global the surface knows best, hence the calculation is done here.

The jacobian is assumed to be initialised, so only the relevant entries are filled

Parameters

  • gctx: The current geometry context object, e.g. alignment

  • jacobian: is the jacobian to be initialized

  • position: is the global position of the parameters

  • direction: is the direction at of the parameters

  • pars: is the parameter vector

const RotationMatrix3D initJacobianToLocal(const GeometryContext &gctx, FreeToBoundMatrix &jacobian, const Vector3D &position, const Vector3D &direction) const

Initialize the jacobian from global to local the surface knows best, hence the calculation is done here.

The jacobian is assumed to be initialised, so only the relevant entries are filled

Return

the transposed reference frame (avoids recalculation)

Parameters

  • jacobian: is the jacobian to be initialized

  • position: is the global position of the parameters

  • direction: is the direction at of the parameters

  • gctx: The current geometry context object, e.g. alignment

bool insideBounds(const Vector2D &lposition, const BoundaryCheck &bcheck = true) const

The insideBounds method for local positions.

Return

boolean indication if operation was successful

Parameters

  • lposition: The local position to check

  • bcheck: BoundaryCheck directive for this onSurface check

SurfaceIntersection intersect(const GeometryContext &gctx, const Vector3D &position, const Vector3D &direction, const BoundaryCheck &bcheck) const

Straight line intersection schema from position/direction.

Return

SurfaceIntersection object (contains intersection & surface)

Parameters

  • gctx: The current geometry context object, e.g. alignment

  • position: The position to start from

  • direction: The direction at start

  • bcheck: the Boundary Check

Intersection intersectionEstimate(const GeometryContext &gctx, const Vector3D &position, const Vector3D &direction, const BoundaryCheck &bcheck) const = 0

Straight line intersection from position and momentum.

Return

Intersection object

Parameters

  • gctx: The current geometry context object, e.g. alignment

  • position: global 3D position - considered to be on surface but not inside bounds (check is done)

  • direction: 3D direction representation - expected to be normalized (no check done)

  • bcheck: boundary check directive for this operation

bool isOnSurface(const GeometryContext &gctx, const Vector3D &position, const Vector3D &momentum, const BoundaryCheck &bcheck = true) const

The geometric onSurface method.

Geometrical check whether position is on Surface

Return

boolean indication if operation was successful

Parameters

  • gctx: The current geometry context object, e.g. alignment

  • position: global position to be evaludated

  • momentum: global momentum (required for line-type surfaces)

  • bcheck: BoundaryCheck directive for this onSurface check

const LocalCartesianToBoundLocalMatrix localCartesianToBoundLocalDerivative(const GeometryContext &gctx, const Vector3D &position) const = 0

Calculate the derivative of bound track parameters local position w.r.t.

position in local 3D Cartesian coordinates

Return

Derivative of bound local position w.r.t. position in local 3D cartesian coordinates

Parameters

  • gctx: The current geometry context object, e.g. alignment

  • position: The position of the paramters in global

void localToGlobal(const GeometryContext &gctx, const Vector2D &lposition, const Vector3D &momentum, Vector3D &position) const = 0

Local to global transformation Generalized local to global transformation for the surface types.

Since some surface types need the global momentum/direction to resolve sign ambiguity this is also provided

Parameters

  • gctx: The current geometry context object, e.g. alignment

  • lposition: local 2D position in specialized surface frame

  • momentum: global 3D momentum representation (optionally ignored)

  • position: global 3D position to be filled (given by reference for method symmetry)

std::string name() const = 0

Return properly formatted class name.

const Vector3D normal(const GeometryContext &gctx, const Vector2D &lposition) const = 0

Return method for the normal vector of the surface The normal vector can only be generally defined at a given local position It requires a local position to be given (in general)

Return

normal vector by value

Parameters

  • gctx: The current geometry context object, e.g. alignment

  • lposition: is the local position where the normal vector is constructed

const Vector3D normal(const GeometryContext &gctx, const Vector3D &position) const

Return method for the normal vector of the surface The normal vector can only be generally defined at a given local position It requires a local position to be given (in general)

Return

normal vector by value

Parameters

  • position: is the global position where the normal vector is constructed

  • gctx: The current geometry context object, e.g. alignment

const Vector3D normal(const GeometryContext &gctx) const

Return method for the normal vector of the surface.

It will return a normal vector at the center() position

Return

normal vector by value

Parameters

  • gctx: The current geometry context object, e.g. alignment

bool operator!=(const Surface &sf) const

Comparison (non-equality) operator.

Parameters

  • sf: Source surface for the comparison

Surface &operator=(const Surface &other)

Assignment operator.

Note

copy construction invalidates the association to detector element and layer

Parameters

  • other: Source surface for the assignment

bool operator==(const Surface &other) const

Comparison (equality) operator The strategy for comparison is (a) first pointer comparison (b) then type comparison (c) then bounds comparison (d) then transform comparison.

Parameters

  • other: source surface for the comparison

double pathCorrection(const GeometryContext &gctx, const Vector3D &position, const Vector3D &direction) const = 0

Calucation of the path correction for incident.

Return

Path correction with respect to the nominal incident.

Parameters

  • gctx: The current geometry context object, e.g. alignment

  • position: global 3D position - considered to be on surface but not inside bounds (check is done)

  • direction: global 3D momentum direction

Polyhedron polyhedronRepresentation(const GeometryContext &gctx, size_t lseg) const = 0

Return a Polyhedron for this object.

Note

An internal surface transform can invalidate the extrema in the transformed space

Return

A list of vertices and a face/facett description of it

Parameters

  • gctx: The current geometry context object, e.g. alignment

  • lseg: Number of segments along curved lines, if the lseg is set to one, only the corners and the extrema are given, otherwise it represents the number of segments for a full 2*M_PI circle and is scaled to the relevant sector

const Acts::RotationMatrix3D referenceFrame(const GeometryContext &gctx, const Vector3D &position, const Vector3D &momentum) const

Return mehtod for the reference frame This is the frame in which the covariance matrix is defined (specialized by all surfaces)

Return

RotationMatrix3D which defines the three axes of the measurement frame

Parameters

  • gctx: The current geometry context object, e.g. alignment

  • position: global 3D position - considered to be on surface but not inside bounds (check is done)

  • momentum: global 3D momentum representation (optionally ignored)

const ISurfaceMaterial *surfaceMaterial() const

Return method for the associated Material to this surface.

Return

SurfaceMaterial as plain pointer, can be nullptr

const std::shared_ptr<const ISurfaceMaterial> &surfaceMaterialSharedPtr() const

Return method for the shared pointer to the associated Material.

Return

SurfaceMaterial as shared_pointer, can be nullptr

std::ostream &toStream(const GeometryContext &gctx, std::ostream &sl) const

Output Method for std::ostream, to be overloaded by child classes.

Parameters

  • gctx: The current geometry context object, e.g. alignment

  • sl: is the ostream to be dumped into

const Transform3D &transform(const GeometryContext &gctx) const

Return method for the surface Transform3D by reference In case a detector element is associated the surface transform is just forwarded to the detector element in order to keep the (mis-)alignment cache cetrally handled.

Return

the contextual transform

Parameters

  • gctx: The current geometry context object, e.g. alignment

SurfaceType type() const = 0

Return method for the Surface type to avoid dynamic casts.

Public Static Functions

template<class T, typename ...Args>
std::shared_ptr<T> makeShared(Args&&... args)

Factory for producing memory managed instances of Surface.

Will forward all parameters and will attempt to find a suitable constructor.

Protected Functions

Surface(std::shared_ptr<const Transform3D> tform = nullptr)

Constructor with Transform3D as a shared object.

Note

also acts as default constructor

Parameters

  • tform: Transform3D positions the surface in 3D global space

Surface(const Surface &other)

Copy constructor.

Note

copy construction invalidates the association to detector element and layer

Parameters

  • other: Source surface for copy.

Surface(const DetectorElementBase &detelement)

Constructor fromt DetectorElementBase: Element proxy.

Parameters

  • detelement: Detector element which is represented by this surface

Surface(const GeometryContext &gctx, const Surface &other, const Transform3D &shift)

Copy constructor with optional shift.

Note

copy construction invalidates the association to detector element and layer

Parameters

  • gctx: The current geometry context object, e.g. alignment

  • other: Source surface for copy

  • shift: Additional transform applied after copying from the source

Protected Attributes

const DetectorElementBase *m_associatedDetElement = {nullptr}

Pointer to the a DetectorElementBase.

const Layer *m_associatedLayer = {nullptr}

The associated layer Layer - layer in which the Surface is be embedded, nullptr if not associated.

const TrackingVolume *m_associatedTrackingVolume = {nullptr}

The assoicated TrackingVolume - tracking volume in case the surface is a boundary surface, nullptr if not associated.

std::shared_ptr<const ISurfaceMaterial> m_surfaceMaterial

Possibility to attach a material descrption.

std::shared_ptr<const Transform3D> m_transform

Transform3D definition that positions (translation, rotation) the surface in global space.