Surface classes

All classes which represent a thin surface in ACTS inherit from the common virtual base class Acts::Surface, which defines the public interface of all surfaces. While the different concrete surface classes are defined by their respective native local coordinate system, the shapes on these surfaces are defined by classes that inherit from Acts::SurfaceBounds, which every surface must provide. In case of boundless surfaces, a special Acts::InfiniteBounds class is available.

Each Acts::Surface instance reports its type from Acts::Surface::type():

enum Acts::Surface::SurfaceType

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

for persistency

Values:

enumerator Cone

enumerator Cylinder

enumerator Disc

enumerator Perigee

enumerator Plane

enumerator Straw

enumerator Curvilinear

enumerator Other

Surface Type	Local Coordinates	Bound Types available
Acts::ConeSurface	\([r\phi, z]\)	Acts::ConeBounds
Acts::CylinderSurface	\([r, \phi]\)	Acts::CylinderBounds
Acts::DiscSurface	\([r, \phi]\)	Acts::RadialBounds, Acts::DiscTrapezoidBounds
Acts::PlaneSurface	\([x, y]\)	Acts::RectangleBounds, Acts::TrapezoidBounds, Acts::InfiniteBounds, Acts::EllipseBounds
Acts::PerigeeSurface, Acts::StrawSurface	\([d, z]\)	Acts::CylinderBounds
Acts::LineSurface	\([d_0, z_0]\)	Acts::LineBounds

Tip

In an ideal setup, the coordinate systems also define the readout measurement directions. In such a case, a track prediction from the propagation will already be in the correct frame of the measurement and residual or compatibility checks will not need additional coordinate transformations.

Plane surface

class PlaneSurface : public Acts::RegularSurface

Class for a planaer in the TrackingGeometry.

The PlaneSurface extends the Surface class with the possibility to convert local to global positions (vice versa).

Subclassed by Acts::PlaneLayer

Public Functions

Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const final

Convert a global position to a local one this is the most generic interface, which is implemented by all surfaces.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

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

• position – is the global position to be converted

• direction – is the direction of the local position (ignored for RegularSurface)

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

virtual Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const override

Global to local transformation.

Note

For planar surfaces the momentum direction is ignored in the global to local transformation

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)

• tolerance – optional tolerance within which a point is considered valid on surface

Returns:

a Result<Vector2> which can be !ok() if the operation fails

Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const = 0

Convert a global position to a local one.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

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

• position – is the global position to be converted

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

virtual SurfaceMultiIntersection intersect(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::Infinite(), ActsScalar tolerance = s_onSurfaceTolerance) const final

Straight line intersection.

mathematical motivation:

the equation of the plane is given by: \( \vec n \cdot \vec x = \vec n \cdot \vec p,\) where \( \vec n = (n_{x}, n_{y}, n_{z})\) denotes the normal vector of the plane, \( \vec p = (p_{x}, p_{y}, p_{z})\) one specific point on the plane and \( \vec x = (x,y,z) \) all possible points on the plane.

Given a line with:\( \vec l(u) = \vec l_{1} + u \cdot \vec v \)

,

the solution for

\( u \) can be written: \( u = \frac{\vec n (\vec p - \vec l_{1})}{\vec n \vec v}\) If the denominator is 0 then the line lies:

• either in the plane

• perpendicular to the normal of the plane

Note

expected to be normalized)

Parameters:

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

• position – The start position of the intersection attempt

• direction – The direction of the intersection attempt, (

• boundaryTolerance – The boundary check directive

• tolerance – the tolerance used for the intersection

Returns:

the SurfaceMultiIntersection object

virtual Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const override

Local to global transformation.

Note

For planar surfaces the momentum direction is ignored in the local to global transformation

Parameters:

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

• lposition – local 2D position in specialized surface frame

Returns:

the global position by value

Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Local to global transformation.

Parameters:

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

• lposition – local 2D position in specialized surface frame

Returns:

The global position by value

Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition, const Vector3 &direction) const final

Local to global transformation.

This is the most generic interface, which is implemented by all surfaces.

Parameters:

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

• lposition – local 2D position in specialized surface frame

• direction – global 3D momentum direction (ignored for RegularSurface)

Returns:

The global position by value

Vector3 normal(const GeometryContext &gctx) const

Get the normal vector, independent of the location.

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

The normal vector

virtual Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const final

Get the normal vector of this surface at a given local position.

return a Vector3 by value

Parameters:

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

• lposition – is the local position is ignored

Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Calculate the normal vector of the surface This overload requires an on-surface local position.

Parameters:

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

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

Returns:

normal vector by value

Vector3 normal(const GeometryContext &gctx, const Vector3 &pos, const Vector3 &direction) const final

Calculate the normal vector of the surface This overload is fully generic, fulfills the Surface interface and accepts a global position and a direction.

For RegularSurface this is equivalent to the normal overload, ignoring the direction

Parameters:

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

• pos – is the global position where the normal vector is constructed

• direction – is the direction of the normal vector (ignored for RegularSurface)

virtual Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const final

Get the normal vector of this surface at a given global position.

Note

The position is required to be on-surface.

Parameters:

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

• position – is the global positiono (for PlaneSurface this is ignored)

Returns:

The normal vector

Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const = 0

Calculate the normal vector of the surface This overload accepts a global position.

Parameters:

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

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

Returns:

normal vector by value

Disc surface

class DiscSurface : public Acts::RegularSurface

Class for a disc surface (or a segment thereof)

The DiscSurface is defined by the local polar coordinates \( (r,phi) \).

The surface transform positions the disc such that the origin is at \( r=0 \), independent of the provided DiscBounds. The normal vector of the disc (i.e., the local \(z\)-axis) is given by \( \vec e_{z} = \vec e_{r} \times\vec e_{phi} \).

The disc surface The only surface type for which the covariance matrix is NOT given in the reference frame. A conversion from polar to cartesian coordinates needs to happen to transfer the local coordinates onto the cartesian reference frame coordinates.

Subclassed by Acts::DiscLayer

Public Functions

Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const final

Convert a global position to a local one this is the most generic interface, which is implemented by all surfaces.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

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

• position – is the global position to be converted

• direction – is the direction of the local position (ignored for RegularSurface)

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

virtual Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const final

Global to local transformation.

Note

the direction is ignored for Disc surfaces in this calculateion

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)

• tolerance – optional tolerance within which a point is considered valid on surface

Returns:

a Result<Vector2> which can be !ok() if the operation fails

Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const = 0

Convert a global position to a local one.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

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

• position – is the global position to be converted

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

virtual SurfaceMultiIntersection intersect(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::Infinite(), ActsScalar tolerance = s_onSurfaceTolerance) const final

Straight line intersection schema.

Mathematical motivation:

the equation of the plane is given by: \( \vec n \cdot \vec x = \vec n \cdot \vec p,\) where \( \vec n = (n_{x}, n_{y}, n_{z})\) denotes the normal vector of the plane, \( \vec p = (p_{x}, p_{y}, p_{z})\) one specific point on the plane and \( \vec x = (x,y,z) \)

all possible points on the plane.

Given a line with:

\( \vec l(u) = \vec l_{1} + u \cdot \vec v \)

,

the solution for

\( u \) can be written: \( u = \frac{\vec n (\vec p - \vec l_{1})}{\vec n \vec v}\) If the denominator is 0 then the line lies:

• either in the plane

• perpendicular to the normal of the plane

Note

expected to be normalized (no checking)

Parameters:

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

• position – The global position as a starting point

• direction – The global direction at the starting point

• boundaryTolerance – The boundary check prescription

• tolerance – the tolerance used for the intersection

Returns:

The SurfaceMultiIntersection object

virtual Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const final

Local to global transformation For planar surfaces the momentum direction is ignored in the local to global transformation.

Parameters:

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

• lposition – local 2D position in specialized surface frame

Returns:

global position by value

Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Local to global transformation.

Parameters:

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

• lposition – local 2D position in specialized surface frame

Returns:

The global position by value

Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition, const Vector3 &direction) const final

Local to global transformation.

This is the most generic interface, which is implemented by all surfaces.

Parameters:

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

• lposition – local 2D position in specialized surface frame

• direction – global 3D momentum direction (ignored for RegularSurface)

Returns:

The global position by value

std::pair<std::shared_ptr<DiscSurface>, bool> mergedWith(const DiscSurface &other, BinningValue direction, bool externalRotation, const Logger &logger = getDummyLogger()) const

Merge two disc surfaces into a single one.

Note

The surfaces need to be compatible, i.e. have disc bounds that align

Note

The returned boolean is false if this is left or counter-clockwise of other, and true if not.

Parameters:

• other – The other disc surface to merge with

• direction – The binning direction: either binR or binPhi

• externalRotation – If true, any phi rotation is done in the transform

• logger – The logger to use

Returns:

The merged disc surface and a boolean indicating if surfaces are reversed

Vector3 normal(const GeometryContext &gctx) const

Get the normal vector, independent of the location.

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

The normal vector

virtual Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const final

Normal vector return.

Parameters:

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

• lposition – The local position is ignored

Returns:

a Vector3 by value

Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Calculate the normal vector of the surface This overload requires an on-surface local position.

Parameters:

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

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

Returns:

normal vector by value

Vector3 normal(const GeometryContext &gctx, const Vector3 &pos, const Vector3 &direction) const final

Calculate the normal vector of the surface This overload is fully generic, fulfills the Surface interface and accepts a global position and a direction.

For RegularSurface this is equivalent to the normal overload, ignoring the direction

Parameters:

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

• pos – is the global position where the normal vector is constructed

• direction – is the direction of the normal vector (ignored for RegularSurface)

virtual Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const final

Get the normal vector of this surface at a given global position.

Note

The position is required to be on-surface.

Parameters:

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

• position – is the global positiono (for DiscSurface this is ignored)

Returns:

The normal vector

Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const = 0

Calculate the normal vector of the surface This overload accepts a global position.

Parameters:

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

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

Returns:

normal vector by value

Cylinder surface

class CylinderSurface : public Acts::RegularSurface

Class for a CylinderSurface in the TrackingGeometry.

It inherits from Surface.

The cylinder surface has a special role in the TrackingGeometry, since it builds the surfaces of all TrackingVolumes at container level for a cylindrical tracking geometry.

Subclassed by Acts::CylinderLayer

Public Functions

Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const final

Convert a global position to a local one this is the most generic interface, which is implemented by all surfaces.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

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

• position – is the global position to be converted

• direction – is the direction of the local position (ignored for RegularSurface)

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

virtual Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const final

Global to local transformation.

Parameters:

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

• position – is the global position to be transformed

• tolerance – optional tolerance within which a point is considered valid on surface

Returns:

a Result<Vector2> which can be !ok() if the operation fails

Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const = 0

Convert a global position to a local one.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

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

• position – is the global position to be converted

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

virtual SurfaceMultiIntersection intersect(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::Infinite(), ActsScalar tolerance = s_onSurfaceTolerance) const final

Straight line intersection schema from position/direction.

If possible returns both solutions for the cylinder

Parameters:

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

• position – The position to start from

• direction – The direction at start

• boundaryTolerance – the Boundary Check Tolerance

• tolerance – the tolerance used for the intersection

Returns:

SurfaceIntersection object (contains intersection & surface)

virtual Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const final

Local to global transformation.

Parameters:

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

• lposition – is the local position to be transformed

Returns:

The global position by value

Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Local to global transformation.

Parameters:

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

• lposition – local 2D position in specialized surface frame

Returns:

The global position by value

Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition, const Vector3 &direction) const final

Local to global transformation.

This is the most generic interface, which is implemented by all surfaces.

Parameters:

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

• lposition – local 2D position in specialized surface frame

• direction – global 3D momentum direction (ignored for RegularSurface)

Returns:

The global position by value

std::pair<std::shared_ptr<CylinderSurface>, bool> mergedWith(const CylinderSurface &other, BinningValue direction, bool externalRotation, const Logger &logger = getDummyLogger()) const

Merge two cylinder surfaces into a single one.

Note

The surfaces need to be compatible, i.e. have cylinder bounds that align, and have the same radius

Note

The returned boolean is false if this is left or counter-clockwise of other, and true if not.

Parameters:

• other – The other cylinder surface to merge with

• direction – The binning direction: either binZ or binRPhi

• externalRotation – If true, any phi rotation is done in the transform

• logger – The logger to use

Returns:

The merged cylinder surface and a boolean indicating if surfaces are reversed

virtual Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const final

Return method for surface normal information.

Note

for a Cylinder a local position is always required for the normal vector

Parameters:

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

• lposition – is the local position for which the normal vector is requested

Returns:

normal vector at the local position by value

Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Calculate the normal vector of the surface This overload requires an on-surface local position.

Parameters:

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

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

Returns:

normal vector by value

Vector3 normal(const GeometryContext &gctx, const Vector3 &pos, const Vector3 &direction) const final

Calculate the normal vector of the surface This overload is fully generic, fulfills the Surface interface and accepts a global position and a direction.

For RegularSurface this is equivalent to the normal overload, ignoring the direction

Parameters:

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

• pos – is the global position where the normal vector is constructed

• direction – is the direction of the normal vector (ignored for RegularSurface)

virtual Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const final

Return method for surface normal information.

Note

for a Cylinder a local position is always required for the normal vector

Parameters:

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

• position – is the global position for which the normal vector is requested

Returns:

normal vector at the global position by value

Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const = 0

Calculate the normal vector of the surface This overload accepts a global position.

Parameters:

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

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

Returns:

normal vector by value

Cone surface

class ConeSurface : public Acts::RegularSurface

Class for a conical surface in the Tracking geometry.

It inherits from Surface.

The ConeSurface is special since no corresponding Track parameters exist since they’re numerical instable at the tip of the cone. Propagations to a cone surface will be returned in curvilinear coordinates.

Subclassed by Acts::ConeLayer

Public Functions

Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const final

Convert a global position to a local one this is the most generic interface, which is implemented by all surfaces.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

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

• position – is the global position to be converted

• direction – is the direction of the local position (ignored for RegularSurface)

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

virtual Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const final

Global to local transformation.

Parameters:

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

• position – is the global position to be transformed

• tolerance – optional tolerance within which a point is considered valid on surface

Returns:

a Result<Vector2> which can be !ok() if the operation fails

Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const = 0

Convert a global position to a local one.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

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

• position – is the global position to be converted

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

virtual SurfaceMultiIntersection intersect(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::Infinite(), double tolerance = s_onSurfaceTolerance) const final

Straight line intersection schema from position/direction.

If possible returns both solutions for the cylinder

Parameters:

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

• position – The position to start from

• direction – The direction at start

• boundaryTolerance – the Boundary Check

• tolerance – the tolerance used for the intersection

Returns:

SurfaceMultiIntersection object (contains intersection & surface)

virtual Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const final

Local to global transformation.

Parameters:

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

• lposition – is the local position to be transformed

Returns:

The global position by value

Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Local to global transformation.

Parameters:

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

• lposition – local 2D position in specialized surface frame

Returns:

The global position by value

Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition, const Vector3 &direction) const final

Local to global transformation.

This is the most generic interface, which is implemented by all surfaces.

Parameters:

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

• lposition – local 2D position in specialized surface frame

• direction – global 3D momentum direction (ignored for RegularSurface)

Returns:

The global position by value

virtual Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const final

Return method for surface normal information.

Parameters:

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

• lposition – is the local position at normal vector request

Returns:

Vector3 normal vector in global frame

Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Calculate the normal vector of the surface This overload requires an on-surface local position.

Parameters:

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

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

Returns:

normal vector by value

Vector3 normal(const GeometryContext &gctx, const Vector3 &pos, const Vector3 &direction) const final

Calculate the normal vector of the surface This overload is fully generic, fulfills the Surface interface and accepts a global position and a direction.

For RegularSurface this is equivalent to the normal overload, ignoring the direction

Parameters:

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

• pos – is the global position where the normal vector is constructed

• direction – is the direction of the normal vector (ignored for RegularSurface)

virtual Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const final

Return method for surface normal information.

Parameters:

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

• position – is the global position as normal vector base

Returns:

Vector3 normal vector in global frame

Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const = 0

Calculate the normal vector of the surface This overload accepts a global position.

Parameters:

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

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

Returns:

normal vector by value

Line surface

Acts::LineSurface is a special kind of surface that depends on a reference direction, typically the unit momentum direction \(\vec d\) of a particle. A point in space is considered on surface if and only if it coincides with the point of closest approach between the direction vector \(\vec d\) and the line direction vector \(\vec z\). As such, the function Acts::LineSurface::globalToLocal() can fail, if the argument position and direction do not fulfill this criterion. It is pure-virtual, meaning that it can not be instantiated on its own.

class LineSurface : public Acts::Surface

Base class for a linear surfaces in the TrackingGeometry to describe dirft tube, straw like detectors or the Perigee It inherits from Surface.

Note

It leaves the type() method virtual, so it can not be instantiated

Subclassed by Acts::PerigeeSurface, Acts::StrawSurface

Public Functions

virtual Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const final

Specified for LineSurface: global to local method without dynamic memory allocation.

This method is the true global -> local transformation. It makes use of globalToLocal and indicates the sign of the Acts::eBoundLoc0 by the given momentum direction.

The calculation of the sign of the radius (or \( d_0 \)) can be done as follows: May \( \vec d = \vec m - \vec c \) denote the difference between the center of the line and the global position of the measurement/predicted state. Then, \( \vec d \) lies in the so-called measurement plane. The latter is determined by the two orthogonal vectors \( \vec{\texttt{measY}} = \vec{e}_z \) and \( \vec{\texttt{measX}} = \vec{\texttt{measY}} \times \frac{\vec{p}}{|\vec{p}|} \).

The sign of the radius (or \( d_{0} \) ) is then defined by the projection of \( \vec{d} \) on \( \vec{measX} \):\( sign = -sign(\vec{d} \cdot \vec{measX}) \)

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 (optionally ignored)

• tolerance – (unused)

Returns:

A Result<Vector2>, which is set to !ok() if the position is not the point of closest approach to the line surface.

virtual SurfaceMultiIntersection intersect(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::Infinite(), ActsScalar tolerance = s_onSurfaceTolerance) const final

Calculate the straight-line intersection with the line surface.

Mathematical motivation:

Given two lines in parameteric form:

\( \vec l_{a}(u) = \vec m_a + u \cdot \vec e_{a} \)

\( \vec l_{b}(\mu) = \vec m_b + \mu \cdot \vec e_{b} \)

The vector between any two points on the two lines is given by:

\( \vec s(u, \mu) = \vec l_{b} - l_{a} = \vec m_{ab} + \mu \cdot \vec e_{b} - u \cdot \vec e_{a} \),

where \( \vec m_{ab} = \vec m_{b} - \vec m_{a} \).

\( \vec s(u_0, \mu_0) \) denotes the vector between the two closest points

\( \vec l_{a,0} = l_{a}(u_0) \) and \( \vec l_{b,0} = l_{b}(\mu_0) \)

and is perpendicular to both, \( \vec e_{a} \) and \( \vec e_{b} \).

This results in a system of two linear equations:

• (i) \( 0 = \vec s(u_0, \mu_0) \cdot \vec e_a = \vec m_{ab} \cdot \vec e_a + \mu_0 \vec e_a \cdot \vec e_b - u_0 \)

• (ii) \( 0 = \vec s(u_0, \mu_0) \cdot \vec e_b = \vec m_{ab} \cdot \vec e_b + \mu_0 - u_0 \vec e_b \cdot \vec e_a \)

Solving (i) and (ii) for \( u \) and \( \mu_0 \) yields:

• \( u_0 = \frac{(\vec m_{ab} \cdot \vec e_a)-(\vec m_{ab} \cdot \vec e_b)(\vec e_a \cdot \vec e_b)}{1-(\vec e_a \cdot \vec e_b)^2} \)

• \( \mu_0 = - \frac{(\vec m_{ab} \cdot \vec e_b)-(\vec m_{ab} \cdot \vec e_a)(\vec e_a \cdot \vec e_b)}{1-(\vec e_a \cdot \vec e_b)^2} \)

The function checks if \( u_0 \simeq 0\) to check if the current position is at the point of closest approach, i.e. the intersection point, in which case it will return an onSurace intersection result. Otherwise, the path length from position to the point of closest approach ( \( u_0 \)) is returned in a reachable intersection.

Note

expected to be normalized

Parameters:

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

• position – The global position as a starting point

• direction – The global direction at the starting point

• boundaryTolerance – The boundary check directive for the estimate

• tolerance – the tolerance used for the intersection

Returns:

is the intersection object

virtual Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition, const Vector3 &direction) const final

Local to global transformation.

Note

for line surfaces the momentum direction is used in order to interpret the drift radius

Parameters:

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

• lposition – is the local position to be transformed

• direction – is the global momentum direction (used to sign the closest approach)

Returns:

global position by value

virtual Vector3 normal(const GeometryContext &gctx, const Vector3 &pos, const Vector3 &direction) const override

Return the surface normal at a given position and direction.

This method is fully generic, and valid for all surface types.

Note

For some surface types, the direction is ignored, but it is not safe to pass in a zero vector!

Parameters:

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

• pos – The position at which to calculate the normal

• direction – The direction at which to calculate the normal

Returns:

The normal vector at the given position and direction

Straw surface

class StrawSurface : public Acts::LineSurface

Class for a StrawSurface in the TrackingGeometry to describe dirft tube and straw like detectors.

Perigee surface

class PerigeeSurface : public Acts::LineSurface

Class describing the Line to which the Perigee refers to.

The Surface axis is fixed to be the z-axis of the Tracking frame. It inherits from StraingLineSurface.

API listings

class 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::LineSurface, Acts::RegularSurface

Public Types

enum SurfaceType

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

for persistency

Values:

enumerator Cone

enumerator Cylinder

enumerator Disc

enumerator Perigee

enumerator Plane

enumerator Straw

enumerator Curvilinear

enumerator Other

Public Functions

virtual ~Surface()

AlignmentToBoundMatrix alignmentToBoundDerivative(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const FreeVector &pathDerivative) 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)

Parameters:

• gctx – The current geometry context object, e.g. alignment change of alignment parameters

• position – global 3D position

• direction – global 3D momentum direction

• pathDerivative – is the derivative of free parameters w.r.t. path length

Returns:

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

virtual AlignmentToPathMatrix alignmentToPathDerivative(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const

Calculate the derivative of path length at the geometry constraint or point-of-closest-approach 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)

Note

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

Parameters:

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

• position – global 3D position

• direction – global 3D momentum direction

Returns:

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

void assignDetectorElement(const DetectorElementBase &detelement)

Assign a detector element.

Parameters:

detelement – Detector element which is represented by this surface

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.

Returns:

plain pointer to the DetectorElement, can be nullptr

const Layer *associatedLayer() const

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

Returns:

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

virtual const SurfaceBounds &bounds() const = 0

Return method for SurfaceBounds.

Returns:

SurfaceBounds by reference

virtual BoundToFreeMatrix boundToFreeJacobian(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const

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

Note

In principle, the input could also be a free parameters vector as it could be transformed to a bound parameters. But the transform might fail in case the parameters is not on surface. To avoid the check inside this function, it takes directly the bound parameters as input (then the check might be done where this function is called).

Parameters:

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

• position – global 3D position

• direction – global 3D momentum direction

Returns:

Jacobian from local to global

virtual Vector3 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

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

center position by value

virtual FreeToBoundMatrix freeToBoundJacobian(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const

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

Note

It assumes the input free parameters is on surface, hence no onSurface check is done inside this function.

Parameters:

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

• position – global 3D position

• direction – global 3D momentum direction

Returns:

Jacobian from global to local

virtual FreeToPathMatrix freeToPathDerivative(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const

Calculate the derivative of path length at the geometry constraint or point-of-closest-approach w.r.t.

free parameters. The calculation is identical for all surfaces where the reference frame does not depend on the direction

Parameters:

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

• position – global 3D position

• direction – global 3D momentum direction

Returns:

Derivative of path length w.r.t. free parameters

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.

Returns:

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.

Returns:

The shared pointer

virtual Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) 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

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

• tolerance – optional tolerance within which a point is considered valid on surface

Returns:

a Result<Vector2> which can be !ok() if the operation fails

virtual bool insideBounds(const Vector2 &lposition, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::None()) const

The insideBounds method for local positions.

Parameters:

• lposition – The local position to check

• boundaryTolerance – BoundaryTolerance directive for this onSurface check

Returns:

boolean indication if operation was successful

virtual SurfaceMultiIntersection intersect(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::Infinite(), ActsScalar tolerance = s_onSurfaceTolerance) const = 0

Straight line intersection schema from position/direction.

Parameters:

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

• position – The position to start from

• direction – The direction at start

• boundaryTolerance – the BoundaryTolerance

• tolerance – the tolerance used for the intersection

Returns:

SurfaceMultiIntersection object (contains intersection & surface)

bool isOnSurface(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::None(), double tolerance = s_onSurfaceTolerance) const

The geometric onSurface method.

Geometrical check whether position is on Surface

Parameters:

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

• position – global position to be evaludated

• direction – global momentum direction (required for line-type surfaces)

• boundaryTolerance – BoundaryTolerance directive for this onSurface check

• tolerance – optional tolerance within which a point is considered on surface

Returns:

boolean indication if operation was successful

virtual ActsMatrix<2, 3> localCartesianToBoundLocalDerivative(const GeometryContext &gctx, const Vector3 &position) const = 0

Calculate the derivative of bound track parameters 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 parameters in global

Returns:

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

virtual Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition, const Vector3 &direction) 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

• direction – global 3D momentum direction

Returns:

The global position by value

virtual std::string name() const = 0

Return properly formatted class name.

virtual Vector3 normal(const GeometryContext &gctx, const Vector3 &pos, const Vector3 &direction) const = 0

Return the surface normal at a given position and direction.

This method is fully generic, and valid for all surface types.

Note

For some surface types, the direction is ignored, but it is not safe to pass in a zero vector!

Parameters:

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

• pos – The position at which to calculate the normal

• direction – The direction at which to calculate the normal

Returns:

The normal vector at the given position and direction

virtual 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

virtual 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

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

Calucation of the path correction for incident.

Note

The position is either ignored, or it is coerced to be on the surface, depending on the surface type.

Parameters:

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

• position – global 3D position

• direction – global 3D momentum direction

Returns:

Path correction with respect to the nominal incident.

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

Return a Polyhedron for this object.

Note

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

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

Returns:

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

virtual Acts::RotationMatrix3 referenceFrame(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const

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

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 (optionally ignored)

Returns:

RotationMatrix3 which defines the three axes of the measurement frame

const ISurfaceMaterial *surfaceMaterial() const

Return method for the associated Material to this surface.

Returns:

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.

Returns:

SurfaceMaterial as shared_pointer, can be nullptr

inline GeometryContextOstreamWrapper<Surface> toStream(const GeometryContext &gctx) const

Helper method for printing: the returned object captures the surface and the geometry context and will print the surface.

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

The wrapper object for printing

std::string toString(const GeometryContext &gctx) const

Output into a std::string.

Parameters:

gctx – The current geometry context object, e.g. alignment

virtual const Transform3 &transform(const GeometryContext &gctx) const

Return method for the surface Transform3 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.

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

the contextual transform

virtual SurfaceType type() const = 0

Return method for the Surface type to avoid dynamic casts.

Public Static Functions

template<class T, typename ...Args>
static inline 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.

Public Static Attributes

static std::array<std::string, SurfaceType::Other> s_surfaceTypeNames

Helper strings for screen output.

Friends

friend struct GeometryContextOstreamWrapper< Surface >