TelecomUtils.jl

DVBS2x <: CapacityComputationType

Structure used to dispatch on speff2snr and snr2speff to simulate the MODCODs of the DVB-S2x air interface.

Note

The threshold values are taken from the error performance chapter (6) of the DVB-S2x standard assuming AWGN conditions

See also: Shannon, NR5G, speff2snr, snr2speff

Convert a point from ENU coordinates to ECEF ones

Fields

• origin::SVector{3,Float64}: ECEF coordinates of the reference CRS origin
• R::RotMatrix3{Float64}: Rotation matrix to align the source to the destination CRS axes
• ellipsoid::Ellipsoid{Float64}: Reference ellipsoid used for the transformation between ECEF and other coordinates

Convert a point from ERA coordinates to ECEF ones

Fields

• origin::SVector{3,Float64}: ECEF coordinates of the reference CRS origin
• R::RotMatrix3{Float64}: Rotation matrix to align the source to the destination CRS axes
• ellipsoid::Ellipsoid{Float64}: Reference ellipsoid used for the transformation between ECEF and other coordinates

Convert a point from UV coordinates to ECEF ones

Fields

• origin::SVector{3,Float64}: ECEF coordinates of the reference CRS origin
• R::RotMatrix3{Float64}: Rotation matrix to align the source to the destination CRS axes
• ellipsoid::Ellipsoid{Float64}: Reference ellipsoid used for the transformation between ECEF and other coordinates

Convert a point from ECEF coordinates to ENU ones

Fields

• origin::SVector{3,Float64}: ECEF coordinates of the reference CRS origin
• R::RotMatrix3{Float64}: Rotation matrix to align the source to the destination CRS axes
• ellipsoid::Ellipsoid{Float64}: Reference ellipsoid used for the transformation between ECEF and other coordinates

Elevation, Range and Azimuth for a target point on space as seen from a source point on or above the earth surface

Fields

• el::Float64: Elevation view angle (0 <= el <= π/2) between source and target point [rad].
• r::Float64: Range (r >= 0) between the source and target points [m].
• az::Float64: Azimuth view angle between source and target point [rad], computed from West to North from the source point perspective. Values provided are automatically converted between -π and π

Constructors

ERA(el::ValidAngle,r::ValidDistance,az::ValidAngle)

ValidAngle is a either a Real number or a Unitful.Quantity of unit either u"rad" or u"°".

ValidDistance is either a Real Number, or a subtype of Unitful.Length.

Convert a point from ECEF coordinates to ERA ones

Fields

• origin::SVector{3,Float64}: ECEF coordinates of the reference CRS origin
• R::RotMatrix3{Float64}: Rotation matrix to align the source to the destination CRS axes
• ellipsoid::Ellipsoid{Float64}: Reference ellipsoid used for the transformation between ECEF and other coordinates

mutable struct EarthModel

Geometrical model of the Earth ellipsoid to be used for all the view angles between satellite and points on earth.

Fields

• ellipsoid::Ellipsoid{Float64}

  Ellipsoid structure, used for the various point of view conversion. Default: SphericalEllipsoid()

• geod::Proj4.geod_geodesic

  Extended geod structure, used for the inverse geodesic problem to compute distance and azimuth between points on earth. (Relies on GeographicLib). Default: Proj4.geod_geodesic(ellipsoid)

A single instance of this structure should be used for all satellites of a given simulation/constellation.
Changes to any of the two fields (via setproperty!) will trigger an automatic recomputation of the other field.
When called without arguments, it defaults to a spherical earth with a radius of 6371 km.

See also: Ellipsoid, SphericalEllipsoid, SatView

Identify a point on or above earth using geodetic coordinates

Fields

• lat::Float64: Latitude (-π/2 <= lat <= π/2) of the point [rad].
• lon::Float64: Longitude of the point [rad].
• alt::Float64: Altitude of the point above the reference earth ellipsoid [m].

Constructors

LLA(lat::ValidAngle,lon::ValidAngle,alt::ValidDistance)
LLA(lat::ValidAngle,lon::ValidAngle) # Defaults to 0m altitude

ValidAngle is a either a Real number or a Unitful.Quantity of unit either u"rad" or u"°".

ValidDistance is either a Real Number, or a subtype of Unitful.Length.

Convert a point from UV coordinates to LLA ones

Fields

• origin::SVector{3,Float64}: ECEF coordinates of the reference CRS origin
• R::RotMatrix3{Float64}: Rotation matrix to align the source to the destination CRS axes
• ellipsoid::Ellipsoid{Float64}: Reference ellipsoid used for the transformation between ECEF and other coordinates

NR5G <: CapacityComputationType

Structure used to dispatch on speff2snr and snr2speff to simulate the MODCODs of the 5G NR air interface.

Note

The thresholds for the 5G approximation are taken from a document by Intel that can be found at this link. The document present a picture of the spectral efficiency vs SNR for various 5G NR MODCODs.

As the tabular data is not provided in the document, the points are extrapolated from the image using this tool.

The thresholds extrapolated from the image with the tool are increased by 1dB, since the values from the picture refer to 10% BLER (Block Error Rate), and we want to use something more akin to QEF (Quasi Error Free) as done for the DVB-S2x thresholds.

For this reason, the results for snr2speff and speff2snr for the 5G NR waveforms will be a linear interpolation based on the extrapolated values, rather than a step function corresponding to existing MODCODs

See also: DVBS2x, Shannon, speff2snr, snr2speff

rv = ReferenceView{T}(lla_or_ecef::Union{LLA, Point3D},earthmodel::EarthModel; kwargs...)

A ReferenceView instance rv tracks the instantaneous position and orientation of an object in space or on earth. It is used to provide convenience methods to assess pointing, distance and visibility between obejcts. It can also be used to extract 3D coordinates (LLA or ECEF) based on pointing angles from the ReferenceView instance.

When initializing rv, two convenience aliases can be used:

• UserView === ReferenceView{:User} can be used to represent users
• SatView === ReferenceView{:Satellite} can be used to represent satellites

The main difference between the two is that the default local CRS for computing pointing and visibilities is West-North-Down (+Z towards nadir) for SatView while it's East-North-Up (+Z towards Zenith) for UserView.

Fields

• ecef::StaticArraysCore.SVector{3, Float64}

  ECEF coordinates of the current satellite position

• lla::LLA

  LLA coordinates of the current satellite position

• earthmodel::EarthModel

  Reference EarthModel used for the projections and for the geodesic computations

• R::Rotations.RotMatrix3{Float64}

  Rotation Matrix to go from the default local CRS to the ECEF CRS

• rot_z::Float64

  Rotation angle [rad] about the z axis to bring the default local CRS to the current one

• rot_y::Float64

  Rotation angle [rad] about the y axis to bring the default local CRS to the current one

• rot_x::Float64

  Rotation angle [rad] about the x axis to bring the default local CRS to the current one

• face::TelecomUtils.Faces

  Reference race of the satellite used for the pointing computations

When multiple ReferenceView objects have to be modelled/tracked, the earthmodel field of all of them should point to the same EarthModel instance, so it should be generated once and then passed to the constructor of all the ReferenceView instances to ensure that all the objects are referring to the same earth model.
Doing so will enforce the same Ellipsoid is shared between all satellites even when it is changed from one of the SatView instances.

To understand how the fields rot_z, rot_y and rot_x are used to model the rotation applied to the default local CRS to the intended one, see the documentation of crs_rotation

The possible values for the reference face (defined with respect to the axes of the local CRS) used for pointing/visibility computations can be found looking at change_reference_face!

See also: change_position!, change_attitude!, change_reference_face!, get_range, get_pointing, get_lla, get_ecef, geod_inverse, get_distance_on_earth, get_nadir_beam_diameter, ExtraOutput, get_visibility, get_mutual_visibility.

Shannon <: CapacityComputationType

Structure used to dispatch on speff2snr and snr2speff to decide the method to use for the computation

See also: DVBS2x, NR5G, speff2snr, snr2speff

Convert a point from ECEF coordinates to UV ones

Fields

• origin::SVector{3,Float64}: ECEF coordinates of the reference CRS origin
• R::RotMatrix3{Float64}: Rotation matrix to align the source to the destination CRS axes
• ellipsoid::Ellipsoid{Float64}: Reference ellipsoid used for the transformation between ECEF and other coordinates

Convert a point from LLA coordinates to UV ones

Fields

• origin::SVector{3,Float64}: ECEF coordinates of the reference CRS origin
• R::RotMatrix3{Float64}: Rotation matrix to align the source to the destination CRS axes
• ellipsoid::Ellipsoid{Float64}: Reference ellipsoid used for the transformation between ECEF and other coordinates

SphericalEllipsoid(r = 6371e3)

Define a spherical ellipsoid of radius r to be used for the various transformation in SatView. Defaults to 6371km radius

p = add_angular_offset(p₀, offset_angles; input_type = :UV, output_type = :UV)
p = add_angular_offset(p₀, θ::ValidAngle, φ::ValidAngle = 0.0; input_type = :UV, output_type = :UV)

Compute the resulting pointing direction p obtained by adding an angular offset specified by angles θ, φ (following the ISO/Physics convention for spherical coordinates) [rad] to the starting position identified by p₀.

The input starting position p₀ can be specified as any iterable of 2 elements and is interpreted (depending on the value of the input_type kwarg) as a set of 2D coordinates specified either as U-V or Theta-Phi [rad].

The output pointing p is always provided as a SVector{2, Float64} and similarly to p₀ can be given as either UV or ThetaPhi coordinates depending on the value of the output_type kwarg.

For both input_type and output_type, the following Symbols are supported:

• :thetaphi, :ThetaPhi and :θφ can be used to represent pointing in ThetaPhi
• :UV and :uv can be used to represent pointing in UV

The offset angles can be provided either as 2nd and 3rd argument to the function (2nd method) or as an iterable containing θ and φ as first and second element respectively (1st method).

This function performs the inverse operation of get_angular_offset so the following code should return true

uv1 = (.3,.4)
uv2 = (-.2,.5)
offset = get_angular_offset(uv1, uv2; input_type = :uv, output_type = :thetaphi)
p = add_angular_offset(uv1, offset; input_type = :uv, output_type = :uv)
all(p .≈ uv2)

See also: get_angular_offset, get_angular_distance

change_attitude!(rv::ReferenceView; rot_z = 0.0, rot_y = 0.0, rot_x = 0.0)

Modify the attitude (local CRS orientation) of rv by recomputing its internal rotation matrix as a product of the default location based one and the attitude rotation based on rot_z, rot_y and rot_x.

See crs_rotation for details on how the attitude rotation matrix is defined and computed.

See also ReferenceView, change_position!, change_Reference_face!

change_position!(rv::ReferenceView, ecef, lla::LLA, R, rot_z, rot_x, rot_y)
change_position!(rv::ReferenceView, ecef::Point3D, lla::LLA; rot_z = 0.0, rot_y = 0.0, rot_x = 0.0)
change_position!(rv::ReferenceView, lla::LLA; rot_z = 0.0, rot_y = 0.0, rot_x = 0.0)
change_position!(rv::ReferenceView, ecef::Point3D; rot_z = 0.0, rot_y = 0.0, rot_x = 0.0)

Change the position of a ReferenceView object rv, also returning as output the modified rv. The function mutates the ecef, lla, R, rot_z, rot_y, rot_x fields of the rv object with the values provided as arguments (when using the 1st method above).
For the remaining methods, the missing arguments are computed automatically.

One would normally use one of the last 3 methods so that the rotation matrix (and eventually either ECEF or LLA) are correctly computed by the function.

The first method avoids any computations but does not validate that provided inputs are correct/consistent and refer to the same position in space. For this reason it should only be used if those values are correctly pre-computed elsewhere and one wants to avoid the duplicate computations.

Note: rot_z, rot_y and rot_x are used to obtain the actual reference CRS to use for the pointing computations. These angles are used to transform the default CRS (which is WND for SatView and ENU for UserView) into the desired CRS. This is done performing a z-y-x intrinsic rotation of the default CRS following the Tait-Bryan Definition.

See also: ReferenceView, get_range, get_pointing, get_lla, get_ecef, get_ecef.

change_reference_face!(rv::ReferenceView, face)

Modify the reference face that is used to compute the visibilities from object rv. The face can be specified using an instance of TelecomUtils.Faces (not exported), a Symbol or an Int as follows:

• TelecomUtils.PositiveX or :PositiveX or 1
• TelecomUtils.PositiveY or :PositiveY or 2
• TelecomUtils.PositiveZ or :PositiveZ or 3
• TelecomUtils.NegativeX or :NegativeX or -1
• TelecomUtils.NegativeY or :NegativeY or -2
• TelecomUtils.NegativeZ or :NegativeZ or -3

See also ReferenceView, change_position!, change_attitude!

compute_sat_position(era2ecef::ECEFfromERA, el, az; h)
compute_sat_position(lla::LLA, el, az; h)
compute_sat_position(ecef::StaticVector{3}, el, az; h)

Given a ECEFfromERA transformation, a target elevation el and azimuth az, and a reference height h [m] of the satellite from the orbit center, provides the ECEF coordinates of the satellite that is seen with angles el and az from the origin of the era2ecef instance at an orbit altitude of h (computed from the earth/orbit center, not from the earth surface).

If called with an LLA or ECEF coordinate as the first argument, it automatically constructs the ECEFfromERA instance era2ecef with the provided coordinate as origin.

Note

The values el and az are used internally to construct ERA objects, so are to be given in [rad] or specified in degrees using ° from Unitful, which is also exported by TelecomUtils.

See also: ERA, ECEF, LLA, ERAfromECEF, ECEFfromERA

R = crs_rotation(;rot_x=0.0, rot_y=0.0, rot_z=0.0)

Create the z-y'-x'' intrinsic Tait-Bryan rotation matrix used to transform/rotate a starting CRS to another one. This is used within ReferenceView to account for satellite attitude or user pointing when defining the final satellite/user centric CRS.

Taking as example a SatView, the default CRS without any attitude rotation is always the WND one centered on the satellite, with the X axis pointing towards West, Y axis towards north and Z axis towards nadir.

Let's call this default CRS as WND and let's assume to have a satellite in a LEO orbit with an inclination of 70 degrees. Let's assume that the satellite is at its ascending node, and that we want to rotate the CRS of the satellite so that the Y axis points in the direction of propagation. To create this new CRS that we will call XYZ, we have to rotate the WND one by 20 degrees clock-wise around the Z axis of the WND CRS.

Assuming to have a point xyz in coordinates relative to the XYZ CRS, we can express the same point as wnd relative to the WND CRS with the following equation:

wnd = crs_rotation(;rot_z=20°) * xyz

db2lin(x::Real) -> Any

Convert a number from dB to linear

f2λ(f::Real) -> Any

Get the wavelength (in m) starting from the frequency (in Hz)

generate_colors(BeamCenters::AbstractVector,N_Colours::Int=4;lattice_type::Symbol=:triangular)

Provide a the coloring breakdown for a given set of lattice points.

Arguments

• BeamCenters → Vector of Tuple or StaticVectors expressing the U-V coordinates of each point in the lattice for which the coloring is being computed
• N_Colours → Number of colors to divide the lattice in. Defaults to 4

keyword Arguments

• lattice_type → Symbol that can either be :triangular or :square, idenifying the type of lattice. Defaults to :triangular

generate_colors(BeamCenters, colordict, L, F; first_color_idx, first_color_coord) -> Any

Provide a the coloring breakdown for a given set of lattice points.

Arguments

• BeamCenters → Array of SVector{2,<:Number} points identifying the beam lattice centers
• colordict → Dictionary of the optimal color order for the given coloring scheme, obtained using get_color_illumination_order
• L → Beam Lattice generating matrix, function of the beam spacing and lattice type and obtained using get_L
• F → Color Lattice generating matrix, function of the number of colors and beam lattice type and obtained using generate_F_reuse_matrix

Keyword Arguments

• first_color_idx → Provide the index of the point in BeamCenters that should be associated with color 1.
• first_color_coord → Provide the coordinates of the point that should be associated with color 1, if both coord and idx are provided, the idx is ignored. Defaults to the giving color 1 to the point in (0,0).

Note

The colors are ordered in such a way that if illuminating the colors in sequential order, the next color is always the one that has the maximum minimum distance with points of the previoulsy illuminated colors (so the one most likely to create lower interference).

generate_hex_lattice(spacing::Real[,f_cond];kwargs...)

Summary

Generate a hexagonal lattice of points (with equal distance between neighboring points). The hexagonal lattice generated by this function has distance between points on the same column √3 times greater than the distance between points on the same row.

Arguments

• spacing → spacing between points

See generate_regular_lattice for a description of f_cond and of the keyword arguments

generate_rect_lattice(spacing_x::Real,spacing_y::Real[,f_cond];kwargs...)

Summary

Generate a rectangular lattice of points (with different spacing among x and y directions)

Arguments

• spacing_x → spacing between points on the x axis
• spacing_y → spacing between points on the y axis

See generate_regular_lattice for a description of f_cond and of the keyword arguments

Generate a regular lattice of points

generate_regular_lattice(dx::Real, dy::Real, ds::Real) -> Any
generate_regular_lattice(dx::Real, dy::Real, ds::Real, f_cond::Function; x0, y0, M, N) -> Any

Arguments

• dx → element spacing on the x axis
• dy → element spacing on the y axis
• ds → displacement along x between rows of elements
• f_cond::Function → function of two arguments (f(x,y) = ...) returning true if element at position x,y must be kept and false otherwise

Keyord Arguments

• x0 = 0 → x coordinate of the origin of the lattice
• y0 = 0 → y coordinate of the origin of the lattice
• M::Int = 70 → Number of elements to generate per row of points before appliying the filtering function f_cond
• N::Int = M → Number of rows of points to generate before appliying the filtering function f_cond

generate_square_lattice(spacing::Real[,f_cond];kwargs...)

Summary

Generate a square lattice of points (with equal spacing among x and y directions)

Arguments

• spacing → spacing between points on both x and y axis

See generate_regular_lattice for a description of f_cond and of the keyword arguments

geod_inverse(geod::Proj4.geod_geodesic, lonlat1::AbstractVector{Cdouble}, lonlat2::AbstractVector{Cdouble})
geod_inverse(geod::Proj4.geod_geodesic, lla1::LLA, lla2::LLA)
geod_inverse(em::EarthModel, lla1::LLA, lla2::LLA)

Solve the inverse geodesic problem.

Args

• g → the geod_geodesic object specifying the ellipsoid.
• lonlat1 → point 1 (degrees), where lat ∈ [-90, 90], lon ∈ [-540, 540)
• lonlat2 → point 2 (degrees), where lat ∈ [-90, 90], lon ∈ [-540, 540)

Outputs

• dist → distance between point 1 and point 2 (meters).
• azi1 → azimuth at point 1 (degrees) ∈ [-180, 180)
• azi2 → (forward) azimuth at point 2 (degrees) ∈ [-180, 180)

Remarks

If either point is at a pole, the azimuth is defined by keeping the longitude fixed, writing lat = 90 +/- eps, and taking the limit as eps -> 0+.

get_L(spacing; lattice_type) -> Any

Get the lattice generating matrix as a function of the lattice_type and of the lattice spacing.

lattice_type has to be either :triangular or :square

get_angular_distance(p₁, p₂; input_type=:UV, output_type=:thetaphi)

Compute the angular distance between the target pointing direction p₂ and the starting pointing direction p₁. The two target pointings can be intepreted as either UV or ThetaPhi coordinates depending on the value of the input_type kwarg.

The output is a scalar that depending on the value of the output_type kwarg represents either the distance in UV, or the angular distance (Δθ) between p₂ and p₁.

For both input_type and output_type, the following Symbols are supported:

• :thetaphi, :ThetaPhi and :θφ can be used to represent pointing in ThetaPhi
• :UV and :uv can be used to represent pointing in UV

Note

All input angles are intepreted as radians unless specified as a Quantity in degrees using ° from Unitful.

The output angles (when output_type is ThetaPhi) are also expressed in radians

This function is similar to get_angular_offset but has a slightly faster implementation in case only the distance is required, rather than the full 2D offset. The following code should evaluate to true

uv1 = (.3,.4)
uv2 = (-.2,.5)
offset = get_angular_offset(uv1, uv2; input_type = :uv, output_type = :thetaphi)
Δθ = get_angular_distance(uv1, uv2; input_type = :uv, output_type = :thetaphi)
offset[1] ≈ Δθ

See also: add_angular_offset, get_angular_offset

get_angular_offset(p₁, p₂; input_type=:UV, output_type=:thetaphi)

Compute the angular offset required to reach the target pointing direction p₂ from starting pointing direction p₁. The two target pointings can be intepreted as either UV or ThetaPhi coordinates depending on the value of the input_type kwarg.

The output is provided as an SVector{2,Float64} and depending on the value of the output_type kwarg it represents either the Δu, Δv offset in UV, or the angular offset (θ and φ) required to reach p₂ from p₁.

For both input_type and output_type, the following Symbols are supported:

• :thetaphi, :ThetaPhi and :θφ can be used to represent pointing in ThetaPhi
• :UV and :uv can be used to represent pointing in UV

Note

All input angles are intepreted as radians unless specified as a Quantity in degrees using ° from Unitful.

The output angles (when output_type is ThetaPhi) are also expressed in radians

This function performs the inverse operation of add_angular_offset so the following code should return true

uv1 = (.3,.4)
uv2 = (-.2,.5)
offset = get_angular_offset(uv1, uv2; input_type = :uv, output_type = :thetaphi)
p = add_angular_offset(uv1, offset; input_type = :uv, output_type = :uv)
all(p .≈ uv2)

Check out get_angular_distance for a slightly faster implementation in case you only require the angular distance rather than the 2D offset.

See also: add_angular_offset, get_angular_distance

get_color_illumination_order(N; lattice_type) -> Tuple{Dictionaries.Dictionary{StaticArraysCore.SVector{2, Int64}, Int64}, StaticArraysCore.SMatrix{2, 2, Int64, 4}}

Get the illumination order to achieve maximum possible distance between already illuminated colors and next illuminated color.

Returns a Dictionary associating each unique color vector obtained from get_deterministic_color_order to the ordering color.

get_distance_on_earth(sv::SatView, p1::Point2D, p2::Point2D[, ::ExtraOutput]; pointing_type::Symbol=:uv, face = sv.face, R)
get_distance_on_earth(p1::LLA, p2::LLA[, ::ExtraOutput]; em = EarthModel())
get_distance_on_earth(p1::UserView, p2::UserView)

Computes the distance [m] between the points on the earth surface (lla1 and lla2) using the reference earth model used by sv.

If the points are not provided as LLA instances, but as angular directions (p1 and p2), lla1 and lla2 as first computed from p1 and p2 using the SatView object sv as reference.

When called with angular directions, the optional argument kind is used to select whether the pointing is expressed in ThetaPhi (kind ∈ (:ThetaPhi, :thetaphi, :θφ)) [rad] or UV coordinates.

If an instance of ExtraOutput is provided as 4th argument, the function also returns the (forward) azimuth angle between lla1 and lla2 (2nd output, [deg]) and the azimuth angle between lla2 and lla1 (third output, [deg])

See also: SatView, get_range, get_pointing, get_lla, get_ecef, geod_inverse, get_nadir_beam_diameter, ExtraOutput.

get_ecef(rv::ReferenceView, pointing::Point2D[, ::ExtraOutput]; pointing_type::Symbol=:uv, h = 0.0, face = rv.face, R = nothing)

Computes the ECEF coordinates of the point that is seen by rv in the direction specified by pointing and is located at a target altitude h [m] above the earth's surface.

If a valid point can not be found because either earth is blocking the view or no point at altitude h can be seen from the provided pointing direction in the rv local CRS (also accounting for desired face), the function returns a SVector{3, Float64} filled win NaNs.

pointing_type is used to select whether the output is returned in UV or ThetaPhi [rad] coordinates. The following symbols are supported for this kwarg:

• :thetaphi, :ThetaPhi and :θφ can be used to represent pointing in ThetaPhi [rad]
• :UV and :uv can be used to represent pointing in UV

When called with an instance of TelecomUtils.ExtraOutput as last argument, the function also returns the coordinated of the identified point in the local CRS of rv.

For details on how to modify the reference pointing direction using the kwargs face and R look at the documentation of get_range

See also: ReferenceView, get_range, get_pointing, get_lla, get_era, get_distance_on_earth, get_visibility, get_mutual_visibility.

get_era(uv::UserView, target::Union{LLA, Point3D, ReferenceView}[, ::ExtraOutput]; face = rv.face, R = nothing)

Computes the ERA coordinates of the provided target as seen from the UserView uv. target can be given either as LLA/ECEF coordinates or directly as another ReferenceView

For details on how to modify the reference pointing direction using the kwargs face and R look at the documentation of get_range

See also: ReferenceView, get_range, get_pointing, get_lla, get_ecef, get_distance_on_earth.

get_lla(rv::ReferenceView, pointing::Point2D[, ::ExtraOutput]; pointing_type::Symbol=:uv, h = 0.0, face = rv.face, R = nothing)

Computes the LLA coordinates of the point that is seen by rv in the direction specified by pointing and is located at a target altitude h [m] above the earth's surface.

If a valid point can not be found because either earth is blocking the view or no point at altitude h can be seen from the provided pointing direction in the rv local CRS (also accounting for desired face), the function returns a SVector{3, Float64} filled win NaNs.

pointing_type is used to select whether the output is returned in UV or ThetaPhi [rad] coordinates. The following symbols are supported for this kwarg:

• :thetaphi, :ThetaPhi and :θφ can be used to represent pointing in ThetaPhi [rad]
• :UV and :uv can be used to represent pointing in UV

When called with an instance of TelecomUtils.ExtraOutput as last argument, the function also returns the coordinated of the identified point in the local CRS of rv.

For details on how to modify the reference pointing direction using the kwargs face and R look at the documentation of get_range

See also: ReferenceView, get_range, get_pointing, get_lla, get_ecef, get_era, get_distance_on_earth, get_visibility, get_mutual_visibility.

p₁, p₂ = get_mutual_pointing(rv1::ReferenceView, rv2::ReferenceView[, ::ExtraOutput]; pointing_type::Symbol=:uv, faces = (rv1.face, rv2.face), Rs=(nothing, nothing), short_circuit = true)

Provide the 2-D angular pointing in both directions between rv1 and rv2:

• p₁ is the pointing of rv2 with respect to rv1
• p₂ is the pointing of rv1 with respect to rv2

pointing_type is used to select whether the outputs are returned in UV or ThetaPhi [rad] coordinates. The following symbols are supported for this kwarg:

• :thetaphi, :ThetaPhi and :θφ can be used to represent pointing in ThetaPhi [rad]
• :UV and :uv can be used to represent pointing in UV

When called with an instance of TelecomUtils.ExtraOutput as last argument, the function also returns the coordinated of the identified point in the local CRS of rv1 (or rv2). In this case:

• p₁ is a tuple containing the pointing as first argument, the local CRS coordinates of rv2 with respect to rv1 as second argument and a NamedTuple with earth blockage data as third argument.
• p₂ is a tuple containing the pointing as first argument, the local CRS coordinates of rv1 with respect to rv2 as second argument and a NamedTuple with earth blockage data as third argument.

faces and Rs are tuples containing the values of face and R for the two ReferenceView objects. faces[1] is used as reference face for rv1 while faces[2] is used for rv2. Similarly for Rs.

The short_circuit kwarg defaults to true and permits to return early from the function to save time. When short_circuit == true, if the fwd pointing is false because of earth blockage, the function will directly return without computing the pointing on the return direction.

For details on how to modify the reference pointing direction using face and R look at the documentation of get_range

See also: ReferenceView, get_range, get_pointing, get_lla, get_ecef, get_distance_on_earth, get_visibility, get_mutual_visibility.

get_mutual_visibility(rv1::ReferenceView, rv2::ReferenceView[, ::ExtraOutput]; boresights = (rv1.face, rv2.face), fov = (90°, 90°), short_circuit = true)

Similar to get_visibility, returns true if rv1 and rv2 can see each other, assuming their antenna boresight directions to be specified by boresights and their maximum Field of View from the boresight to be specified by fovs.

boresights and fovs are tuples containing the values of boresight and fov for the two ReferenceView objects. boresights[1] is used as reference boresight for rv1 while boresights[2] is used for rv2. Similarly for fovs.

The short_circuit kwarg defaults to true and permits to return early from the function to save time. When short_circuit == true, if the fwd visibility is false, the function will directly return without computing the visibility angle on the return direction.

Each boresight value inside the boresights kwarg can be specified either as a face (compatible with the input types specified in change_reference_face!) or as a 3D pointing vector using either 3 elements Tuple, Vector or SVector. If a 3D vector is provided, the function normalizes to unitary norm automatically.

Each fov value inside the fovs kwarg must be specified as an angle in radians if provided as a simple Number. To provide a fov in degress, directly use ° from Unitful re-exported by TelecomUtils.

When called with an instance of TelecomUtils.ExtraOutput as last argument, the function also returns a Tuple containing the full outputs (as if called with ExtraOutput) of get_visibility for each direction (rv1 to rv2 and vice-versa).

See also: get_pointing, get_mutual_pointing, ReferenceView, get_range, get_pointing, get_lla, get_ecef, get_distance_on_earth, get_visibility.

get_nadir_beam_diameter(sv, scan_3db)

Computes the diameter [m] on earth of a beam pointed at nadir from the satellite position identified by sv and assuming a 3db beamwidth identified by the scan angle scan_3db [deg] at which the beam pattern is 3dB below the peak.

The computation computes the diameter along the U direction and takes into account the reference ellipsoid of sv, so the resulting diameter is dependent on the satellite lat/lon position

See also: SatView, get_range, get_pointing, get_lla, get_ecef, geod_inverse, get_distance_on_earth.

get_pointing(rv::ReferenceView, target::Union{LLA, Point3D, ReferenceView}[, ::ExtraOutput]; pointing_type::Symbol=:uv, face = rv.face, R=nothing)

Provide the 2-D angular pointing at which the target point (specified as LLA, ECEF or as another ReferenceView) is seen from the ReferenceView object rv.

pointing_type is used to select whether the output is returned in UV or ThetaPhi [rad] coordinates. The following symbols are supported for this kwarg:

• :thetaphi, :ThetaPhi and :θφ can be used to represent pointing in ThetaPhi [rad]
• :UV and :uv can be used to represent pointing in UV

When called with an instance of TelecomUtils.ExtraOutput as last argument, the function also returns the coordinated of the identified point in the local CRS of rv as second output, and a NamedTuple containing information on the earth blockage status as third argument.

For details on how to modify the reference pointing direction using the kwargs face and R look at the documentation of get_range

See also: get_mutual_pointing, ReferenceView, get_range, get_pointing, get_lla, get_ecef, get_distance_on_earth, get_visibility, get_mutual_visibility.

get_range(rv::ReferenceView,uv::Point2D[, ::ExtraOutput]; h = 0.0, face = rv.face, R = nothing)
get_range(rv::ReferenceView,target::Union{LLA, Point3D, ReferenceView}[, ::ExtraOutput]; face = rv.face, R = nothing)

Get the range [in m] between the reference view rv (Satellite or User) and a target point. The target point can be identified in two ways:

• Providing the uv pointing uv and the reference altitude h [m] above the ellipsoid (first method)
• directly passing in a point expressed either as LLA, as a Point3D representing its ECEF coordinates, or as another instance of ReferenceView (second method).

The pointing is assumed to be referred to the specified face of the ReferenceView. When the location identified by the provided pointing is not visible either because it's blocked by earth or because it's in a direction not visible from the specified face, NaN is returned.

See change_reference_face! for supported identification of the face kwarg.

When called with an instance of TelecomUtils.ExtraOutput as last argument, the function also returns the coordinated of the identified point in the local CRS of rv.

The kwarg R represents the 3D Rotation Matrix that translates a vector from ECEF coordinates to the coordinates of the desired local CRS around rv. By default (if R === nothing) this rotation matrix is computed based on the rotation matrix of the rv object and on the selected reference face.

See also: ReferenceView, get_era, get_mutual_pointing, get_pointing, get_lla, get_ecef, get_distance_on_earth.

get_visibility(rv::ReferenceView, target::Union{LLA, Point3D, ReferenceView}[, ::ExtraOutput]; boresight = rv.face, fov = 90°)

Returns true if target is visible from rv assuming an antenna boresight direction specified by boresight and a maximum Field of View from the boresight specified by fov.

The boresight kwarg can be specified either as a face (compatible with the input types specified in change_reference_face!) or as a 3D pointing vector using either 3 elements Tuple, Vector or SVector. If a 3D vector is provided, the function normalizes to unitary norm automatically.

The fov kwarg must be specified as an angle in radians if provided as a simple Number. To provide a fov in degress, directly use ° from Unitful re-exported by TelecomUtils.

When called with an instance of TelecomUtils.ExtraOutput as last argument, the function also returns the pointing angle θ between rv and target as second argument, and the direction in ECEF coordinates from rv to target.

See also: get_pointing, get_mutual_pointing, ReferenceView, get_range, get_pointing, get_lla, get_ecef, get_distance_on_earth, get_mutual_visibility.

lin2db(x::Real) -> Any

Convert a number from linear to dB

new_color_order(n::Int64, color_order_dict::Dictionaries.Dictionary{StaticArraysCore.SVector{2, I}, I} where I, F) -> Vector

Find the new optimal color ordering when starting from color n rather than from 1.

Arguments

• n → New starting color.
• color_order_dict → original optimal color order for the current coloring scheme obtained via get_color_illumination_order.
• F → lattice generating matrix for the current coloring scheme, obtained using generate_F_reuse_matrix.

snr2speff(DVBS2x(), linear_snr)
snr2speff(Shannon(), linear_snr)
snr2speff(NR5G(), linear_snr)

Computes the minimum the spectral efficiency η [b/s/Hz] that can be achieved given the input SNR [linear] linear_snr.

The first argument specifies whether to use the DVBS2x or 5G NR thresholds or the Shannon formula for the computation.

See also: DVBS2x, Shannon, NR5G, speff2snr

speff2snr(DVBS2x(), η)
speff2snr(Shannon(), η)
speff2snr(NR5G(), η)

Computes the minimum SNR [linear] that is required to achieve the target spectral efficiency η [b/s/Hz].

The first argument specifies whether to use the DVBS2x or 5G NR thresholds or the Shannon formula for the computation

See also: DVBS2x, Shannon, NR5G, snr2speff

λ2f(λ::Real) -> Any

Get the frequency (in Hz) starting from the wavelength (in m)