Table of Contents

Class CoordinateTransformations

Namespace
VirtualLabAPI.Core.Numerics
Assembly
VirtualLabAPI.dll

Provides static conversion functions from one coordinate system to another one, among others

  • from pixel to physical coordinates and vice versa,
  • from spatial to spectral sampling and vice versa, and
  • from an arbitrary coordinate to a coordinate within a period

But be aware that in case the physical coordinate (0; 0) is not bound to the center of a pixel (which is the case for data arrays, but not for complex amplitudes), the VirtualLabAPI.Core.Numerics.SamplingConversions class should be used to convert between pixel and physical coordinates and vice versa.

public static class CoordinateTransformations
Inheritance
CoordinateTransformations
Inherited Members

Methods

ConvertWalkParameterTo2DPosition(double, VectorD, bool)

Converts a one-dimensional “walk parameter” to a 2D position either on an ellipse or a rectangle.

public static VectorD ConvertWalkParameterTo2DPosition(double walkParameter, VectorD sizeOfAperture, bool isEllipticAperture)

Parameters

walkParameter double

The (relative) walk parameter: 0 means the starting point (x_max; 0), 1 means we walked one round counterclockwise around the circumference .

sizeOfAperture VectorD

The size of the elliptic or rectangular aperture.

isEllipticAperture bool

If set to true an elliptic aperture is assumed, otherwise a rectangular one.

Returns

VectorD

The matching 2D position on the circumference of the aperture.

CoordinateWithinPeriod(double, double, double)

Ensures that the given coordinate lies within -period/2 ... +period.X/2. If not it is "wrapped" into this range.

public static double CoordinateWithinPeriod(double coordinate, double period, double centerOfPeriod = 0)

Parameters

coordinate double

The coordinate to convert.

period double

The period which gives the range the coordinate must fit in.

centerOfPeriod double

The center of the period to get the coordinate within.

Returns

double

The converted period.

CoordinateWithinPeriod(Vector3D, Vector3D)

Ensures that the given coordinate lies within (-period.X/2, -period.Y/2, 0) ... (+period.X/2, +period.Y/2, +period.Z). If not it is "wrapped" into this range.

public static Vector3D CoordinateWithinPeriod(Vector3D coordinate, Vector3D period)

Parameters

coordinate Vector3D

The coordinate to convert.

period Vector3D

The period which gives the range the coordinate must fit in.

Returns

Vector3D

The converted period.

CoordinateWithinPeriod(VectorD, VectorD, VectorD)

Ensures that the given coordinate lies within (-period.X/2, -period.Y/2) ... (+period.X/2, +period.Y/2). If not it is "wrapped" into this range.

public static VectorD CoordinateWithinPeriod(VectorD coordinate, VectorD period, VectorD centerOfPeriod = default)

Parameters

coordinate VectorD

The coordinate to convert.

period VectorD

The period which gives the range the coordinate must fit in.

centerOfPeriod VectorD

The center of the period to get the coordinate within.

Returns

VectorD

The converted period.

GetCentralPixel(SamplingParameters)

This method gives the central pixel, i.e. that pixel having the physical coordinate (0; 0). This implicitly assumes that the physical center is in the center of a pixel; for even sampling the pixel top right from the actual center is returned.

public static Vector GetCentralPixel(SamplingParameters samplingParameters)

Parameters

samplingParameters SamplingParameters

The sampling parameters (needed for conversion).

Returns

Vector

The central pixel in whose center the physical coordinate (0; 0) [e.g. (0 m; 0 m)] is located.

GetRotationQuaternionForRotatingOneDirectionVectorToAnother(Vector3D, Vector3D)

The method calculates a rotation quaternion for rotating one direction vector to another. If the source vector v1 and the target vector v2 are normalized, the resulting quaternion m fulfills the equation m*v1 = v2. If the vectors are not normalized, the product of m and v1 will give a new vector with the direction of v2 and the length of v1.

public static Quaternion GetRotationQuaternionForRotatingOneDirectionVectorToAnother(Vector3D sourceVector, Vector3D targetVector)

Parameters

sourceVector Vector3D

Vector to be rotated.

targetVector Vector3D

Vector to be the target of the rotation.

Returns

Quaternion

A rotation quaternion for rotating sourceVector to targetVector.

GetRotationQuaternionFromAnyCStoAnyOtherCS(CartesianCoordinateSystem, CartesianCoordinateSystem)

Calculates the rotation quaternion Q that transforms a coordinate x1 from one coordinate system to another via x2 = Q * x1.

public static Quaternion GetRotationQuaternionFromAnyCStoAnyOtherCS(CartesianCoordinateSystem sourceCS, CartesianCoordinateSystem targetCS)

Parameters

sourceCS CartesianCoordinateSystem

Source coordinate system.

targetCS CartesianCoordinateSystem

Target coordinate system.

Returns

Quaternion

The quaternion which describes the rotation from one CS to another.

PointFromPhysicalToPixelCoordinates(double, int, double, bool)

Converts a given point in physical coordinates into a point in (double valued) pixel coordinates. It is assumed that the physical coordinate 0 is in the center of the data.

public static double PointFromPhysicalToPixelCoordinates(double pointInPhysical, int samplingPoints, double samplingDistance, bool zeroPointInPixel)

Parameters

pointInPhysical double

The point given in physical coordinates

samplingPoints int

Number of 1D sampling points.

samplingDistance double

Sampling distance (1D).

zeroPointInPixel bool

If set to true the physical coordinate 0 is in the center of a pixel. This is mandatory for ComplexAmplitude and HarmonicFieldsSet objects. If set to false, this coordinate can also lie between pixels (in case of even sampling).

Returns

double

the point in (double valued) pixel coordinates

PointFromPhysicalToPixelCoordinates(VectorD, SamplingParameters, bool)

Converts a given point in physical coordinates into a point in (double valued) pixel coordinates. It is assumed that the physical coordinate 0 is in the center of the data.

public static VectorD PointFromPhysicalToPixelCoordinates(VectorD pointInPhysical, SamplingParameters samplingParameters, bool zeroPointInPixel)

Parameters

pointInPhysical VectorD

The point given in physical coordinates

samplingParameters SamplingParameters

The sampling parameters (needed for conversion)

zeroPointInPixel bool

If set to true the physical coordinate 0 is in the center of a pixel. This is mandatory for ComplexAmplitude and HarmonicFieldsSet objects. If set to false, this coordinate can also lie between pixels (in case of even sampling).

Returns

VectorD

the point in (double valued) pixel coordinates

PointFromPixelToPhysicalCoordinates(double, int, double, bool)

Converts a given one-dimensional point in (double value) pixel coordinates into a position in physical coordinates. It is assumed that the physical coordinate 0 is in the center of the data.

public static double PointFromPixelToPhysicalCoordinates(double pointInPixels, int numberOfSamplingPoints, double samplingDistance, bool zeroPointInPixel)

Parameters

pointInPixels double

The one-dimensional point given in double pixel coordinates

numberOfSamplingPoints int

The number of sampling points (needed for conversion).

samplingDistance double

The sampling distance (needed for conversion).

zeroPointInPixel bool

If set to true the physical coordinate 0 is in the center of a pixel. This is mandatory for ComplexAmplitude and HarmonicFieldsSet objects. If set to false, this coordinate can also lie between pixels (in case of even sampling).

Returns

double

The point in physical coordinates.

PointFromPixelToPhysicalCoordinates(int, int, double, bool)

Converts a given one-dimensional point in pixel coordinates into a position in physical coordinates. It is assumed that the physical coordinate 0 is in the center of the data.

public static double PointFromPixelToPhysicalCoordinates(int pointInPixels, int numberOfSamplingPoints, double samplingDistance, bool zeroPointInPixel)

Parameters

pointInPixels int

The one-dimensional point given in pixel coordinates

numberOfSamplingPoints int

The number of sampling points (needed for conversion).

samplingDistance double

The sampling distance (needed for conversion).

zeroPointInPixel bool

If set to true the physical coordinate 0 is in the center of a pixel. This is mandatory for ComplexAmplitude and HarmonicFieldsSet objects. If set to false, this coordinate can also lie between pixels (in case of even sampling).

Returns

double

The point in physical coordinates.

PointFromPixelToPhysicalCoordinates(Vector, SamplingParameters)

Converts a given point in pixel coordinates into a point in physical coordinates. \static{}

public static VectorD PointFromPixelToPhysicalCoordinates(Vector pointInPixels, SamplingParameters samplingParameters)

Parameters

pointInPixels Vector

The point given in pixel coordinates

samplingParameters SamplingParameters

The sampling parameters (needed for conversion)

Returns

VectorD

the point in physical coordinates

PointFromPixelToPhysicalCoordinates(VectorD, SamplingParameters, bool, LocationFixation2D)

Converts a given point in (double valued) pixel coordinates into a point in physical coordinates. It is assumed that the physical coordinate 0 is in the center of the data.

public static VectorD PointFromPixelToPhysicalCoordinates(VectorD pointInPixels, SamplingParameters samplingParameters, bool zeroPointInPixel, LocationFixation2D vertexToReturn = LocationFixation2D.Center)

Parameters

pointInPixels VectorD

The point given in (double valued) pixel coordinates

samplingParameters SamplingParameters

The sampling parameters (needed for conversion)

zeroPointInPixel bool

If set to true the physical coordinate (0; 0) is always in the center of a pixel. This is mandatory for ComplexAmplitude and HarmonicFieldsSet objects. If set to false, this coordinate can also lie between pixels (in case of even sampling).

vertexToReturn LocationFixation2D

Optional parameter to specify which vertex of a pixel is returned. By default the center of the pixel is returned.

Returns

VectorD

The point in physical coordinates.

RotateExcentrical(CartesianCoordinateSystem, Quaternion, Position)

Method to do a rotation of a coordinate system, but not about its own origin but about another center of rotation

public static CartesianCoordinateSystem RotateExcentrical(CartesianCoordinateSystem csToBeRotated, Quaternion rotationQuaternion, Position rotationCenterInReferenceCS)

Parameters

csToBeRotated CartesianCoordinateSystem

Coordinate system to be rotated

rotationQuaternion Quaternion

Quaternion that describes the rotation

rotationCenterInReferenceCS Position

Center of rotation, defined in the reference coordinate system of the cs to be rotated.

Returns

CartesianCoordinateSystem

rotated coordinate system

SpatialSamplingToSpectralSampling(SamplingParameters)

Converts a spatial sampling to a spectral sampling. Therefor, the resulting sampling is calculated from the original field size via the Fourier theorem. Works also for conversion from spectral to spatial.

public static SamplingParameters SpatialSamplingToSpectralSampling(SamplingParameters samplingParameters)

Parameters

samplingParameters SamplingParameters

The original sampling parameters.

Returns

SamplingParameters

The resulting sampling parameters.

TransformAny3DCoordinates2CoordinatesDefinedInAnyOtherCS(Vector3D, CartesianCoordinateSystem, CartesianCoordinateSystem)

Transforms a given coordinate in ℝ³ from one coordinate system to another.

public static Vector3D TransformAny3DCoordinates2CoordinatesDefinedInAnyOtherCS(Vector3D coordinates2Btransformed, CartesianCoordinateSystem sourceCS, CartesianCoordinateSystem targetCS)

Parameters

coordinates2Btransformed Vector3D

Vector to be transformed.

sourceCS CartesianCoordinateSystem

Source coordinate system.

targetCS CartesianCoordinateSystem

Target coordinate system.

Returns

Vector3D

The coordinate in reference to targetCS.

TransformAnyCS2CSdefinedInAnyOtherCS(CartesianCoordinateSystem, IProvidesPositioningReferences, string)

Transforms a given coordinate system into any other coordinate system

public static CartesianCoordinateSystem TransformAnyCS2CSdefinedInAnyOtherCS(CartesianCoordinateSystem cs2Btransformed, IProvidesPositioningReferences newPositioningReferenceProvider, string newPositioningReferenceKey)

Parameters

cs2Btransformed CartesianCoordinateSystem

coordinate system to be transformed

newPositioningReferenceProvider IProvidesPositioningReferences

reference provider of the coordinate system that shall be used as new reference

newPositioningReferenceKey string

key that identifies the coordinate system that shall be used as new reference in the reference provider class

Returns

CartesianCoordinateSystem

Coordinate system with reference to the coordinate system which is given by the reference provider object.

TransformAnyDirectionVector3D2DirectionVector3DDefinedInAnyOtherCS(Vector3D, CartesianCoordinateSystem, CartesianCoordinateSystem)

Transforms a given direction vector in ℝ³ from one coordinate system to another. Important: This operation will be restricted to a rotation of the vector and will NOT take the new coordinate system's origin into account. So the length of the vector will be kept.

public static Vector3D TransformAnyDirectionVector3D2DirectionVector3DDefinedInAnyOtherCS(Vector3D directionVector2Btransformed, CartesianCoordinateSystem sourceCS, CartesianCoordinateSystem targetCS)

Parameters

directionVector2Btransformed Vector3D

Vector to be transformed.

sourceCS CartesianCoordinateSystem

Source coordinate system.

targetCS CartesianCoordinateSystem

Target coordinate system.

Returns

Vector3D

The coordinate in reference to targetCS.

TransformAnyPosition2PositionDefinedInAnyOtherCS(Position, IProvidesPositioningReferences, string)

Transforms a given position into any other coordinate system

public static Position TransformAnyPosition2PositionDefinedInAnyOtherCS(Position pos2Btransformed, IProvidesPositioningReferences newPositioningReferenceProvider, string newPositioningReferenceKey)

Parameters

pos2Btransformed Position

position to be transformed

newPositioningReferenceProvider IProvidesPositioningReferences

reference provider of the coordinate system that shall be used as new reference

newPositioningReferenceKey string

key that identifies the coordinate system that shall be used as new reference in the reference provider class

Returns

Position

Position with reference to the coordinate system which is given by the reference provider object.

TransformAnyPositionVector3D2PositionVector3DDefinedInAnyOtherCS(Vector3D, CartesianCoordinateSystem, CartesianCoordinateSystem)

Transforms a given position vector in ℝ³ from one coordinate system to another. Important: This operation will NOT be restricted to a rotation of the vector but will take the new coordinate system's origin into account. So the length of the vector may be changed.

public static Vector3D TransformAnyPositionVector3D2PositionVector3DDefinedInAnyOtherCS(Vector3D positionVector2Btransformed, CartesianCoordinateSystem sourceCS, CartesianCoordinateSystem targetCS)

Parameters

positionVector2Btransformed Vector3D

Vector to be transformed.

sourceCS CartesianCoordinateSystem

Source coordinate system.

targetCS CartesianCoordinateSystem

Target coordinate system.

Returns

Vector3D

The coordinate in reference to targetCS.

TransformBasevectorsFromOneCStoAnyOtherCS(CoordinateSystemBaseVectors, CartesianCoordinateSystem, CartesianCoordinateSystem)

Transforms a set of coordinate system base vectors from one coordinate system into another.

public static CoordinateSystemBaseVectors TransformBasevectorsFromOneCStoAnyOtherCS(CoordinateSystemBaseVectors baseVectors, CartesianCoordinateSystem sourceCS, CartesianCoordinateSystem targetCS)

Parameters

baseVectors CoordinateSystemBaseVectors

Set of base vectors to be transformed.

sourceCS CartesianCoordinateSystem

Source coordinate system.

targetCS CartesianCoordinateSystem

Target coordinate system.

Returns

CoordinateSystemBaseVectors

The transformed set of base vectors.

TransformCSdefinedInGlobalsCS2LocalCS(CartesianCoordinateSystem, IProvidesPositioningReferences, string)

Transforms a coordinate system, given in relation to the global coordinate system, to one defined relative to a given reference coordinate system.

public static CartesianCoordinateSystem TransformCSdefinedInGlobalsCS2LocalCS(CartesianCoordinateSystem csInGlobal, IProvidesPositioningReferences positioningReferenceProvider, string positioningReferenceKey)

Parameters

csInGlobal CartesianCoordinateSystem

Coordinate system (given in relation to the global coordinate system) to be transformed.

positioningReferenceProvider IProvidesPositioningReferences

Object which provides the coordinate system that serves as reference for this position.

positioningReferenceKey string

Key for the coordinate system (contained by PositioningReferenceProvider) which shall serve as reference for this position

Returns

CartesianCoordinateSystem

Coordinate system defined relative to a given reference coordinate system.

TransformInternalPosition2PositionInGlobalCS(Position)

Transforms a position, given in relation to its reference coordinate system to the global coordinate system (For repeated calls try to use an object of type TransformationsForCartesianCoordinateSystems.)

public static Position TransformInternalPosition2PositionInGlobalCS(Position internalPosition)

Parameters

internalPosition Position

Position (in relation to its reference coordinate system) to be transformed.

Returns

Position

Position in relation to the global coordinate system.

TransformInternalPosition2PositionInHigherReferenceCS(Position)

Transforms a position, given in relation to its reference coordinate system to the next higher reference coordinate system (For repeated calls try to use an object of type TransformationsForCartesianCoordinateSystems.)

public static Position TransformInternalPosition2PositionInHigherReferenceCS(Position internalPosition)

Parameters

internalPosition Position

Position (in relation to its reference coordinate system) to be transformed.

Returns

Position

Position in relation to the reference coordinate system of the former reference coordinate system

TransformLocalCS2CSdefinedInGlobalCS(CartesianCoordinateSystem)

Transforms a coordinate system, given in relation to its reference coordinate system, to one defined relative to the global coordinate system.

public static CartesianCoordinateSystem TransformLocalCS2CSdefinedInGlobalCS(CartesianCoordinateSystem localCS)

Parameters

localCS CartesianCoordinateSystem

Coordinate system (given in relation to its reference coordinate system) to be transformed.

Returns

CartesianCoordinateSystem

Coordinate system defined relative to the global coordinate system.

TransformPositionInGlobalCS2InternalPosition(Position, IProvidesPositioningReferences, string)

Transforms a position, given in relation to the global coordinate system to a reference coordinate system. (For repeated calls try to use an object of type TransformationsForCartesianCoordinateSystems.)

public static Position TransformPositionInGlobalCS2InternalPosition(Position externalPosition, IProvidesPositioningReferences positioningReferenceProvider, string positioningReferenceKey)

Parameters

externalPosition Position

Position (in relation to the global coordinate system) to be transformed.

positioningReferenceProvider IProvidesPositioningReferences

Object which provides the coordinate system that serves as reference for this position.

positioningReferenceKey string

Key for the coordinate system (contained by PositioningReferenceProvider) which shall serve as reference for this position

Returns

Position

Position in relation to the new reference coordinate system.