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
-
enumerator Cone
Surface Type |
Local Coordinates |
Bound Types available |
---|---|---|
\([r\phi, z]\) |
||
\([r, \phi]\) |
||
\([r, \phi]\) |
||
\([x, y]\) |
|
|
\([d, z]\) |
||
\([d_0, z_0]\) |
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 theResult
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 theResult
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 thedirection
- 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
-
Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const final
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 theResult
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 theResult
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
ifthis
is left or counter-clockwise ofother
, andtrue
if not.- Parameters:
other – The other disc surface to merge with
direction – The binning direction: either
binR
orbinPhi
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 thedirection
- 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
-
Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const final
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 theResult
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 theResult
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
ifthis
is left or counter-clockwise ofother
, andtrue
if not.- Parameters:
other – The other cylinder surface to merge with
direction – The binning direction: either
binZ
orbinRPhi
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 thedirection
- 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
-
Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const final
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 theResult
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 theResult
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 thedirection
- 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
-
Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const final
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 theActs::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 theposition
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 anonSurace
intersection result. Otherwise, the path length fromposition
to the point of closest approach ( \( u_0 \)) is returned in areachable
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
anddirection
.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 Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const final
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
-
enumerator Cone
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
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
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 abad_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
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 abad_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
anddirection
.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
-
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, unsigned int quarterSegments = 2u) const = 0
Return a Polyhedron for surface objects.
Note
In order to symmetrize the code between sectoral and closed cylinders in case of closed cylinders, both (-pi, pi) are given as separate vertices
Note
An internal surface transform can invalidate the extrema in the transformed space
- Parameters:
gctx – The current geometry context object, e.g. alignment
quarterSegments – The number of segemtns to approximate a 0.5*pi sector, which represents a quarter of the full circle
- 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
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.
-
void visualize(IVisualization3D &helper, const GeometryContext &gctx, const ViewConfig &viewConfig = s_viewSurface) const
Public Static Functions
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 >
-
enum SurfaceType