Table of Contents

Class ProfileHeightInterface

Namespace
VirtualLabAPI.Core.OpticalSystems
Assembly
VirtualLabAPI.dll

This is the base class for all optical surfaces which can be described by a profile height function h(x, y). The profile height corresponds to the z-position of the optical interface at a given lateral position.

[Serializable]
public abstract class ProfileHeightInterface : OpticalInterface, ISerializable, IDeserializationCallback, IDisposable, IEquatable<IObjectBase>, ICloneable
Inheritance
ObjectBase
SerializableObjectBase
ManualSerialization
SpreadSheetObject
ProfileHeightInterface
Implements
IEquatable<IObjectBase>
Inherited Members

Constructors

ProfileHeightInterface()

Default constructor.

public ProfileHeightInterface()

ProfileHeightInterface(VectorD, bool)

Constructor calls just the corresponding constructor of the OpticalInterface base class.

public ProfileHeightInterface(VectorD apertureDiameter, bool apertureHasEllipticalShape)

Parameters

apertureDiameter VectorD
apertureHasEllipticalShape bool

Properties

AllowLateralScaling

Gets whether lateral scaling (setting the scaling factors β and γ) is allowed. For always periodical surfaces (= grating surfaces), this is never allowed, because you then get problems if these surfaces are rotated about the z-axis.

public virtual bool AllowLateralScaling { get; }

Property Value

bool

ContainsFresnelZones

If true the interpolation and the finding of ray intersection points is optimized for optical surfaces that contain Fresnel zones, i.e. 2Pi, 4Pi, 6Pi, … jumps. The sampling points represent the height of the surface on a special point and are interpolated using a special cubic interpolation which maintains the Fresnel zones. If false the interpolation and finding of the ray intersection points is optimized for function that have high frequency surface profiles but no Fresnel zones. Multiple ray intersections are taken into account. Setting this property to true will set the properties IsPixelated and IsSmoothInterface properties to false.

public virtual bool ContainsFresnelZones { get; set; }

Property Value

bool

FresnelZonesRelativePositionOnZAxis

Gets and sets the relative position on the z-axis for the Fresnel zones.

public double FresnelZonesRelativePositionOnZAxis { get; set; }

Property Value

double

HeightLevelDifferenceForQuantization

Gets and sets difference between two consecutive height levels if the surface is quantized.

public double HeightLevelDifferenceForQuantization { get; }

Property Value

double

IsAlwaysPeriodical

Gets whether the interface is always periodical (true) or whether the user can make the interface periodical (false).

public virtual bool IsAlwaysPeriodical { get; }

Property Value

bool

IsFixedPixelation

Gets whether the pixelation can be set by the user (true) or whether it is fixed (false).

public virtual bool IsFixedPixelation { get; }

Property Value

bool

IsFixedQuantization

Gets whether the quantization can be set by the user (true) or whether it is fixed (false).

public virtual bool IsFixedQuantization { get; }

Property Value

bool

IsPeriodical

If true the structure is periodical. Otherwise non-periodical.

public bool IsPeriodical { get; set; }

Property Value

bool

IsPixelated

true indicates surfaces that have a pixelated structure (for example surfaces that were fabricated by a pixel-oriented machine). Every sampling point represents a rectangular pixel with the width of the sampling distance. The top of the pixel is perpendicular to the optical axis. The pixel borders are parallel to the optical axis. If false the sampling points are interpolated using a cubic interpolation. Multiple ray intersections are taken into account. Setting this property will set the properties IsSmoothInterface and ContainsFresnelZones to false.

public virtual bool IsPixelated { get; set; }

Property Value

bool

IsQuantized

If true it indicates that the height profile has discrete height levels. Only pixelated height profiles can be quantized. This means if somebody changes this flag to true the IsPixelated flag will be also set to true.

public virtual bool IsQuantized { get; set; }

Property Value

bool

IsRotationalSymmetric

Gets whether the given surface is rotational symmetric. The following conditions must be fulfilled for rotational symmetry:

  • The surface must not be periodical.
  • The definition area must be rotational symmetric (i.e. circular).
  • The surface must be either an aspherical surface, a conical surface or a untilted plane surface – or a combined surface containing only such surfaces.
public bool IsRotationalSymmetric { get; }

Property Value

bool

true if the surface is rotational symmetric, otherwise false.

IsSmoothInterface

Used for surfaces that contain no high frequent profile height function. The sampling points represent the height of the interface on a special point and are smoothly interpolated. Multiple ray intersections are not taken into account. A gradient search algorithm is used to find the intersection points of rays. Setting this property to true will set IsPixelated and ContainsFresnelZones to false.

public virtual bool IsSmoothInterface { get; set; }

Property Value

bool

MaximumQuantizedHeight

Gets and sets the maximum height of a quantized surface.

public double MaximumQuantizedHeight { get; }

Property Value

double

MaximumUserDefinedQuantization

Sets and gets the maximum height for user-defined quantization mode.

public double MaximumUserDefinedQuantization { get; set; }

Property Value

double

MinimumQuantizedHeight

Gets and sets the minimum height of a quantized surface.

public double MinimumQuantizedHeight { get; }

Property Value

double

MinimumUserDefinedQuantization

Sets and gets the minimum height for user-defined quantization mode.

public double MinimumUserDefinedQuantization { get; set; }

Property Value

double

NumberOfHeightLevels

Contains the number of height levels of a quantized height profile. If a specific number of height levels is set the IsQuantized flag is switched to true.

public virtual int NumberOfHeightLevels { get; set; }

Property Value

int

Period

The period length in x- and y-direction of the grating used for 2d and 3d rigorous analysis. If the structure is not periodical the period must be equal to the aperture diameter of the optical surface. The default value of the period is equal to the aperture size so the element is not really periodically.

public virtual VectorD Period { get; set; }

Property Value

VectorD

PixelSize

For pixelated surfaces only. If IsPixelated is false the property may return any value.

public VectorD PixelSize { get; set; }

Property Value

VectorD

QuantizationModeOfInterface

Sets and gets the quantization mode of the surface.

public QuantizationMode QuantizationModeOfInterface { get; set; }

Property Value

QuantizationMode

TotalProfileHeight

For surfaces with Fresnel zones only. The total height of the profile. This means the height of the 2Pi, 4Pi, ... jumps of the surface. If ContainsFresnelZones is false the property may return any value.

public virtual double TotalProfileHeight { get; set; }

Property Value

double

Methods

CalculateInterfaceDerivativeDXDY(VectorD, out double, out double, bool, bool)

Calculates the derivative of the interface in x- and y-direction on the specified position. Both derivatives are set to zero if the interface is quantized, pixelated or if we are outside the inner definition area. Scaling is also considered by this function.

public void CalculateInterfaceDerivativeDXDY(VectorD position, out double mx, out double my, bool calculateFirstDerivative = true, bool useScaling = true)

Parameters

position VectorD

Position to calculate the derivative on.

mx double

The derivative in x-direction

my double

The derivative in y-direction

calculateFirstDerivative bool

Optional parameter specifying whether to use this function to calculate the first (true= or second (false) derivative of the height profile.

useScaling bool

Optional parameter specifying whether to scale the derivative according to ScalingAlpha. ScalingBeta, and ScalingGamma. Needs only to be false for the numerical calculation of the second derivative to avoid scaling twice.

CalculateNormalVector(VectorD)

Calculates the normal vector for the given lateral position. The normal vector points always in positive z-direction. To invert the normal vector (so that it shows in negative z-direction) multiply -1. An inversion is necessary to calculate the refraction of rays traveling in negative z-direction.

public virtual Vector3D CalculateNormalVector(VectorD position)

Parameters

position VectorD

Lateral position for the normal vector calculation.

Returns

Vector3D

Normal vector of the interface for the given lateral position.

CalculateSecondDerivative(VectorD, out double, out double)

Calculates the second derivative of the interface profile in x- and y-direction on the specified position. Both derivatives are set to zero if the interface is quantized, pixelated or if we are outside the inner definition area. Scaling is also considered by this function.

public void CalculateSecondDerivative(VectorD position, out double secondDerivativeX, out double secondDerivativeY)

Parameters

position VectorD

Position to calculate the derivative on.

secondDerivativeX double

The second derivative in x-direction.

secondDerivativeY double

The second derivative in y-direction.

Clone()

Creates deep copy of object. The ParentSystem member is deleted in the copy of the spread sheet object.

public override object Clone()

Returns

object

Equals(object, EqualityIntent)

Determines whether the specified object is equal to this instance in a physical sense.

public override bool Equals(object otherObject, EqualityIntent equalityIntent)

Parameters

otherObject object

The object to compare with this instance.

equalityIntent EqualityIntent

Defines what kind of equality you want to check when comparing two objects, for example all values or physical equality.

Returns

bool

true if the specified object is equal to this instance; otherwise, false.

EvaluateHeightOutsideInnerDefinitionArea(bool)

Evaluates the height outside the inner definition area.

public double EvaluateHeightOutsideInnerDefinitionArea(bool includeQuantization = true)

Parameters

includeQuantization bool

Optional parameter to indicate whether the calling function treats the quantization correctly. Needs to be set to false if the z-extension of the unquantized surface is determined to calculate the height levels of the quantized surface.

Returns

double

The height outside the outer definition area.

EvaluateHeightOutsideOuterDefinitionArea(bool)

Evaluate the height outside the outer definition area.

public double EvaluateHeightOutsideOuterDefinitionArea(bool includeQuantization = true)

Parameters

includeQuantization bool

Optional parameter to indicate whether the calling function treats the quantization correctly. Needs to be set to false if the z-extension of the unquantized interface is determined to calculate the height levels of the quantized interface.

Returns

double

The height outside the outer definition area.

Export()

Export function for the underlying surface. Opens a settings dialog.

public void Export()

GetIntersectionPoint(ref PlaneWaveData, ref double, bool, out Vector3D)

This function handles the apertures, periodization and scaling. GetIntersectionPointOfElementaryInterface is called by this function and handles the elementary interface.

This function calculates the intersection point between the input ray and the present interface. The search is always done in the propagation direction of the ray. This means is the IsPositiveZ property of the ray is true then the search runs in positive z-direction. If the IsPositiveZ property is false the search runs in negative z-direction. After success it returns the position of the intersection point and the normal vector of the interface.

public bool GetIntersectionPoint(ref PlaneWaveData ray, ref double zPosition, bool findLeftRightTransition, out Vector3D normalVector)

Parameters

ray PlaneWaveData

In the beginning of the function this ray is the incident ray. After the success of the function the x,y position of the ray is the x,y position of the intersection point.

zPosition double

The z-position of the ray. Since all rays start and end usually in the same plane the z-position is not stored inside the PlaneWaveData structure. So during the tracing of one PlaneWaveData the z-position has to be stored separate.

findLeftRightTransition bool

If true the function tries to find an interface transition between the medium globally on the left side of the interface and the medium globally on the right side of the interface. If false the function tries to find an interface transition between the medium on the right side of the interface and on the medium on the left side of the interface.

normalVector Vector3D

The normal vector of the interface on the intersection point. The normal vector points in positive z-direction for rays traveling in positive z-direction and it points in negative z-direction for rays traveling in negative z-direction.

Returns

bool

True if an intersection point was found.

GetIntersectionPointOfElementaryInterfaceAnalytical(Vector3D, Vector3D, out Vector3D) 

public virtual bool GetIntersectionPointOfElementaryInterfaceAnalytical(Vector3D inPosition, Vector3D inDirection, out Vector3D intersection)

Parameters

inPosition Vector3D
inDirection Vector3D
intersection Vector3D

Returns

bool

GetIntersectionsWithLine(double, double, bool, double, double, double, out double[])

Calculate the intersections of the surface with a line parallel to X-axis or to Y-axis with given start and end coordinate. May be overridden in derived interfaces.

public double[] GetIntersectionsWithLine(double zPos, double lineShift, bool searchParallelToXAxis, double minValueOfFreeCoordinate, double maxValueOfFreeCoordinate, double transitionPointAccuracy, out double[] signOfDerivatives)

Parameters

zPos double

Z-position of the line (2-D FMM) that is searched for media transitions. Must be given in interface cs(!)

lineShift double

Line shift (1) on Y-axis iff searchParallelXAxis == true, (2) on X-axis iff searchParallelXAxis == false

searchParallelToXAxis bool

Iff true, the search line is parallel to X-axis; iff false, search line is parallel to Y-axis

minValueOfFreeCoordinate double

Start coordinate on the line. Interface coordinates.

maxValueOfFreeCoordinate double

End coordinate on the line. Interface coordinates.

transitionPointAccuracy double

Accuracy Factor.

signOfDerivatives double[]

Out parameter for sign of derivatives at intersection points.

Returns

double[]

Double array with intersection points on that line. Null if no intersections can be found.

GetPointInterfaceRelation(Vector3D)

Checks the position of a point relative to the surface. A point can be in the medium on the right side of a surface, in the medium on the left side of the surface or lateral outside of the surface.

public override PointInterfaceRelation GetPointInterfaceRelation(Vector3D position)

Parameters

position Vector3D

The position to check.

Returns

PointInterfaceRelation

A PointInterfaceRelation enum indicating the relation of the point to the surface.

GetPolygonPoints(double, double, double)

Gets the polygon points representing this interface including scaling, periodization, consideration of the definition areas, ...

public override sealed List<VectorD> GetPolygonPoints(double startCoordinate, double endCoordinate, double accuracyFactor = 1)

Parameters

startCoordinate double

The x-coordinate of the start point (y = 0).

endCoordinate double

The x-coordinate of the end point (y = 0).

accuracyFactor double

The accuracy factor. This optional parameter is equal to one by default. 20 × the accuracy polygon points are calculated whereas it is ensured that an odd number of polygon points is returned.

Returns

List<VectorD>

A list of VectorD objects storing x-position and corresponding height.

IsAbsorbingAtPosition(VectorD)

Returns true if the surface absorbs the light at the position (x,y), otherwise false.

public bool IsAbsorbingAtPosition(VectorD position)

Parameters

position VectorD

The lateral position to check.

Returns

bool

True if the surface absorbs the light at the position (x,y), otherwise false.

IsConsistent(ref List<ConsistenyErrorOrWarning>, EditedInType)

Method to check whether the interface is defined consistently.

public override bool IsConsistent(ref List<ConsistenyErrorOrWarning> errorList, EditedInType editedFrom = EditedInType.Component)

Parameters

errorList List<ConsistenyErrorOrWarning>

Reference to a list which can already contain some messages. If the interface is inconsistent the error messages are appended to this list. If null, a new list is created.

editedFrom EditedInType

Specifies from where this interface is edited. If this optional parameter is set to EditedInType.Catalog then a SpreadSheetObject having no subsequent medium is allowed even if AllowedSubsequentMedium is true. The reasoning for this optional parameter is that optical interfaces in the catalog do not have a subsequent medium.

Returns

bool

true, if the interface is consistent, otherwise false.

MinimumFeatureSize(double)

Gets the minimum feature size of the surface.

public VectorD MinimumFeatureSize(double accuracyFactor)

Parameters

accuracyFactor double

The accuracy factor used for the calculation of the minimum feature size.

Returns

VectorD

The minimum feature size (in meters) for both x- and y-direction.

ProfileHeight(double, double)

Profile height calculation which includes pixelation, quantization and scaling in x-, y- and z- direction.

public double ProfileHeight(double x, double y)

Parameters

x double

The lateral x-position.

y double

The lateral y-position.

Returns

double

Returns the profile height depending on the lateral position.

ProfileHeight(VectorD)

Profile height calculation which includes pixelation, quantization and scaling in x-, y- and z- direction.

public double ProfileHeight(VectorD position)

Parameters

position VectorD

Position on which the height profile shall be calculated.

Returns

double

Height value on that position.

ProfileHeight(VectorD, out bool)

Profile height calculation which includes pixelation, quantization and scaling in x-, y- and z- direction.

public double ProfileHeight(VectorD position, out bool isAbsorbed)

Parameters

position VectorD

the position on which the height profile shall be calculated

isAbsorbed bool

Out parameter specifying whether or not light on the given position is absorbed by an aperture.

Returns

double

The height value on the position.

ProfileHeight(VectorD, out bool, bool, bool, double?)

Profile height calculation which includes pixelation, quantization and scaling in x-, y- and z-direction.

public double ProfileHeight(VectorD position, out bool isAbsorbed, bool includeQuantization, bool subtractHeightOffset = true, double? nanValue = null)

Parameters

position VectorD

the position on which the height profile shall be calculated

isAbsorbed bool

Out parameter specifying whether or not light on the given position is absorbed by an aperture.

includeQuantization bool

To apply quantization one needs to know the total profile height (without quantization). Thus this parameters allows to switch of the quantization during calculation of that total profile height.

subtractHeightOffset bool

Optional parameter to avoid recursion - as the offset to be subtracted is the height at the position (0, 0) without the offset subtracted.

nanValue double?

The value with which NaNs are replaced. If this optional parameter is not specified, the value outside the (inner) definition area is used.

Returns

double

The height value on the position.