HeavyRF Table Functions

Summary of parameters for base and optional versions

The HeavyRF package provides the following system table functions:

• tf_rf_prop_max_signal (directional antennas)

• tf_rf_prop_max_signal (isotropic antennas)

• tf_rf_prop

tf_rf_prop_max_signal (Directional Antennas and Terrain Attenuation)

Taking a set of point elevations and a set of signal source locations as input, tf_rf_prop_max_signal executes line-of-sight 2.5D RF signal propagation from the provided sources over a binned 2.5D elevation grid derived from the provided terarin locations, calculating the max signal in dBm at each grid cell, using the formula for free-space power loss. The terrain should contain columns for ground elevation, terrain elevation (which should be greater than or equal to the ground elevation height), and terrain attenuation in dbm per meter, specifying the degree to which signal will be attenuated if it passes between the terrain and ground elevations (i.e. through a tree or building). The RF source ID contributing the strongest signal is also outputted.

When geographic_coords is set to true, x and y input coordinates are assumed to be lon/lat degrees. A best-fit conversion to a meters coordinate system is executed using the change in meters per lon/lat degree at the centroid of the input terrain, using the haversine distance formula. For convenience and optimal performance, tf_rf_prop_max_signal enables filter push-down by default, such that filters on the outputs rf_source_id, x, y, and elevation_amsl_meters are pushed down to the respective inputs in the rf_sources and terrain_elevations Cursor subqueries.

SELECT * FROM TABLE(
   tf_rf_prop_max_signal(
      rf_sources => CURSOR(
         SELECT 
            rf_source_id,
            rf_source_x,
            rf_source_y, 
            rf_source_z,
            rf_source_signal_strength_watts,
            rf_source_signal_frequency_mhz,
            rf_source_antenna_azimuth_degrees,
            rf_source_antenna_downtilt_degrees,
            rf_source_antenna_type
         FROM
            rf_sources_table
      ),
      terrain_elevations => CURSOR(
         SELECT
             x,
             y,
             ground_elevation_amsl_meters,
             terrain_elevation_amsl_meters,
             terrain_attenuation_dbm_per_meter 
          FROM
             terrain_table
      ),
      antenna_patterns => CURSOR(
         SELECT
             antenna_type,
             antenna_gain,
             antenna_horizontal_degrees,
             antenna_horizontal_attenuation,
             antenna_vertical_degrees,
             antenna_vertical_attenuation
          FROM
             antennas_table
      ),
      rf_source_z_is_relative_to_terrain => <rf_source_is_relative_to_terrain>, 
      geographic_coords => <geographic_coords>,
      bin_dim_meters => <bin_dim_meters>, 
      assumed_receiver_height_agl => <assumed_receiver_height_agl>,
      max_ray_travel_meters => <max_ray_travel_meters>, 
      initial_rays_per_source => <initial_rays_per_source>,
      rays_per_bin_autosplit_threshold => <rays_per_bin_autosplit_threshold>,
      min_receiver_signal_strength_dbm => <min_receiver_signal_strength_dbm>,
      default_source_height_agl_meters => <default_source_height_agl_meters>,
      ray_step_bin_multiple => <ray_step_bin_multiple>,
      loop_grain_size => <loop_grain_size>, 
   )
)

Input Arguments

Parameter	Cursor	Description	Data Types
rf_source_id	rf_sources	ID of the RF source. Used in the output for each grid cell to denote the RF source contributing the strongest signal.	Column<INT | BIGINT | TEXT ENCODING DICT>
rf_source_x	rf_sources	x-coordinate of the RF source, assumed to be in longitude degrees. Whether FLOAT or DOUBLE, rf_source_x must be the same type as all other columns in the rf_sources CURSOR, excluding rf_source_z.	Column <FLOAT | DOUBLE>
rf_source_y	rf_sources	y-coordinate of the RF source, assumed to be in longitude degrees. Whether FLOAT or DOUBLE, rf_source_y must be the same type as all other columns in the rf_sources CURSOR, excluding rf_source_z.	Column <FLOAT | DOUBLE> (must be same type as rf_source_x)
rf_source_z_meters	rf_sources	z-coordinate of the RF source, in meters. If rf_source_is_relative_to_terrain is set to true, meters are relative to the terrain height; for example, an input of 20 is 20 meters above ground level. Otherwise, it is absolute height above sea level; 20 is 20 meters above mean sea level (AMSL).	Column <FLOAT | DOUBLE>
rf_source_power_watts	rf_sources	Power in Watts (W) of the transmitting antenna. rf_source_power_watts must be the same type s all other columns in the rf_sources CURSOR, excluding rf_source_z.	Column <FLOAT | DOUBLE> (must be same type as rf_source_x)
rf_source_freq_mhz	rf_sources	Frequency in megahertz (MHz) of the transmitting antenna. rf_source_freq_mhz must be the same type s all other columns in the rf_sources CURSOR, excluding rf_source_z.	Column <FLOAT | DOUBLE> (must be same type as rf_source_x)
rf_source_antenna_azimuth_degrees	rf_sources	Azimuth in degrees of the transmitting antenna. rf_source_antenna_azimuth_degrees must be the same type s all other columns in the rf_sources CURSOR, excluding rf_source_z.	Column <FLOAT | DOUBLE> (must be same type as rf_source_x)
rf_source_antenna_downtilt_degrees	rf_sources	Downtilt in degrees of the transmitting antenna. rf_source_antenna_gain must be the same type s all other columns in the rf_sources CURSOR, excluding rf_source_z.	Column <FLOAT | DOUBLE> (must be same type as rf_source_x)
rf_source_antenna_type	rf_sources	The type of antenna deployed. Used to lookup the antenna parameters in the antenna patterns table for the matching type entry. Must be a text type. Antenna types that are null or have no match in the antenna_patterns table will be considered omnidirectional.	Column <TEXT ENCODING DICT>
terrain_x	terrain_elevations	x-coordinate of the terrain. If geographIc_coords is true, this is assumed to be in longitude degrees, otherwise in meters. Whether FLOAT or DOUBLE, terrain_x and terrain_y must be the same type.	Column <FLOAT | DOUBLE>
terrain_y	terrain_elevations	y-coordinate of the terrain. If geographIc_coords is true, this is assumed to be in latitude degrees, otherwise in meters. Whether FLOAT or DOUBLE, terrain_x and terrain_y must be the same type.	Column <FLOAT | DOUBLE> (must be same type as terrain_x)
ground_elevation_amsl_meters	terrain_elevations	Elevation of the ground, in meters above sea level. Ground is considered to fully occlude signal	Column <FLOAT | DOUBLE (should be same type as terrain_elevation_amsl_meters and terrain_attenuation_dbm_per_meter)
terrain_elevation_amsl_meters	terrain_elevations	Maximum elevation of the terrain (could be a building, vegetation, or the ground itself), in meters above sea level. Should be greater than or equal to ground_elevation_amsl_meters	Column <FLOAT | DOUBLE (should be same type as ground_elevation_amsl_meters and terrain_attenuation_dbm_per_meter)
terrain_attenuation_dbm_per_meter	terrain_elevations	Attenuation in dBm for any ray that passes above ground_elevation_amsl_meters and below terrain_elevation_amsl_meters. If type of terrain is present in the source table, the attenuation value can be looked up from another terrain attenuation table via a join.	Column <FLOAT | DOUBLE (should be same type as ground_elevation_amsl_meters and terrain_elevation_amsl_meters)
antenna_type	antenna_patterns	Antenna type as text arguement. Used to join with rf_sources table. If antenna_type is 'default', the patterns for this type will be used for all rf_sources entry with type 'default', null, or that otherwise do not have a corresponding antenna_type entry in the antenna_patterns table.	Column <TEXT ENCODING DICT>
antenna_gain	antenna_patterns	The gain in dBm for this antenna type.	Column <FLOAT | DOUBLE> (all numeric arguments in antenna_patterns CURSOR must be the same type)
antenna_horizontal_degrees	antenna_patterns	An array specifying a set of degrees from 0 to 360, with 0 degrees representing due North, 90 degrees due East, 180 degrees due South, and 270 degrees due West. The corresponding indexed entry in the antenna_horizontal_attenuations specifies the attenuation for the degree entry. An entry will be created for each integer degree, with missing entries linearly interpolated from the closest neighbors below and above that degree. Entries can but do not have to be in order.	Column <FLOAT | DOUBLE> (all numeric arguments in antenna_patterns CURSOR must be the same type)
antenna_horizontal_attenuation	antenna_patterns	An array specifying the amount of attenuation, in dBm, for the corresponding entry with the same index in the antenna_horizontal_degrees array.	Column <FLOAT | DOUBLE> (all numeric arguments in antenna_patterns CURSOR must be the same type)
antenna_vertical_degrees	antenna_patterns	An array specifying a set of degrees from 0 to 360, with 0 degrees representing forward along the horizon along the direction of the antenna azimuth, 90 degrees directly overhead, 180 degrees in the direction opposite the antenna azimuth, and 270 degrees directly toward the ground. Entries below 0 can also be used and will be wrapped appropriately (i.e. -90 degrees = 270 degrees = directly toward the ground). The corresponding indexed entry in the antenna_vertical_attenuations specifies the attenuation for the degree entry. An entry will be created for each integer degree, with missing entries linearly interpolated from the closest neighbors below and above that degree. Entries can but do not have to be in order.	Column <FLOAT | DOUBLE> (all numeric arguments in antenna_patterns CURSOR must be the same type)
antenna_vertical_attenuation	antenna_patterns	An array specifying the amount of attenuation, in dBm, for the corresponding entry with the same index in the antenna_vertical_degrees array.	Column <FLOAT | DOUBLE> (all numeric arguments in antenna_patterns CURSOR must be the same type)
rf_source_z_is_relative_to_terrain	N/A	true specifies that rf_source_z_meters values are the height in meters above ground level. false indicates the values are height in meters above sea level.	BOOLEAN
geographic_coords	N/A	true specifies that the input x and y arguments for RF sources and terrain elevations are in lon/lat degrees. false specifies that the data is already in a local meter coordinate system.	BOOLEAN
bin_dim_meters	N/A	Width and height of each binned terrain cell, which is the unit of granularity over which the RF propagation algorithm is executed.	DOUBLE
assumed_receiver_height_agl	N/A	Height in meters above ground_elevation_amsl_meters from the terrains_elevation cursor to measure the signal strength at, i.e. the modeled height of the receiving handset above ground.	DOUBLE
max_ray_travel_meters	N/A	Maximum meters for which to model RF propagation from any given source. Lower values can increase performance, but potentially miss the strongest repeater for a terrain cell that is further away than the value set.	DOUBLE
initial_rays_per_source	N/A	Number of initial 2.5D rays to propagate from each source. Since rays are automatically split as needed as they radiate out from the rf source, this can be safely set to a low number such as 64 to maximize performance.	BIGINT
rays_per_bin_autosplit_threshold	N/A	Minimum ratio of radial rays per bin, below which the ray is split into two to ensure ray coverage of terrain bins as distance increases from the rf_source. 1.5 is a safe default value to use.	DOUBLE
min_receiver_signal_strength_dbm	N/A	The minimum signal strength threshold in dBm to continue propagating a signal ray from a source. Rays stop being propagated when either the distance from the source exceeds the limit set by max_ray_travel_meters, or the signal strength (as measured by free-space power loss, assuming no obstructions in the path) drops below the value set by min_receiver_signal_strength_dbm.	DOUBLE
assumed_source_height_above_ground	N/A	The default height in meters above ground level for a source if there is no input data in the terrain_elevations for the terrain bin in which a given rf_source lies.	DOUBLE
ray_step_bin_multiple	N/A	The step, in number of bins (can be fractional), used to increment the ray propagation as the ray radiates out from the RF source. Lower values of this (below 1.0) can increase accuracy of the simulation, but decrease performance. Values above 1.0 are not recommended because they can cause gaps in the output.	DOUBLE
loop_grain_size	N/A	The size in number of rays at which to parallelize over; threads will process rays in groups of at least this size. A reasonable value might be 10, although changing this number may improve performance, depending on hardware configuration.	BIGINT

Output Columns

Name	Description	Data Type
x	x-centroid of the output terrain bin. In lon/lat degrees in longitude degrees if geographic_coords is set to true, otherwise in meters.	Column<FLOAT | DOUBLE> (same type as rf_source_x and rf_source_y input columns)
y	y-centroid of the output terrain bin. In lon/lat degrees in longitude degrees if geographic_coords is set to true, otherwise in meters.	Column<FLOAT | DOUBLE> (same type as rf_source_x and rf_source_y input columns)
elevation_amsl_meters	Maximum elevation of all input terrain data falling in the output XY terrain bin, in meters above sea level.	Column<FLOAT | DOUBLE> (same type as rf_source_z_meters input column)
rf_source_id	ID of the repeater with the strongest signal for the grid cell.	Column<INT | BIGINT | TEXT ENCODING DICT>(same type as RF sources ID input)
max_signal_strength_dbm	The maximum signal strength in dBm for a given XY-terrain bin.	Column<FLOAT | DOUBLE> (same type as rf_source_x and rf_source_y input)

Example

SELECT
  rf_source_id,
  ST_X(
    ST_TRANSFORM(
      ST_SETSRID(
        ST_POINT(x, y),
        32610
      ),
      4326
    )
  ) as lon,
  ST_Y(
    ST_TRANSFORM(
      ST_SETSRID(
        ST_POINT(x, y),
        32610
      ),
      4326
    )
  ) as lat,
  CAST(
    CASE
      WHEN max_rf_signal_strength_dbm IS NULL THEN -130.0
      ELSE max_rf_signal_strength_dbm
    END AS FLOAT
  ) AS rf_signal_strength_dbm
FROM
  TABLE(
    tf_rf_prop_max_signal(
      rf_sources => CURSOR (
        SELECT
          id,
          x,
          y,
          z,
          power_watts,
          freq_mhz,
          antenna_azimuth,
          antenna_downtilt,
          antenna_type
        FROM
          seattle_rf_sources
      ),
      terrain_elevations => CURSOR (
        SELECT
          CAST(x_utm AS FLOAT) AS x,
          CAST(y_utm AS FLOAT) AS y,
          CAST(z + 0.0001 AS float) AS elevation
        FROM
          seattle_expanded_lidar_tiled
      ),
      antenna_patterns => CURSOR (
        SELECT
          antenna_type,
          antenna_gain,
          antenna_horizontal_degrees,
          antenna_horizontal_attenuations,
          antenna_vertical_degrees,
          antenna_vertical_attenuations
        FROM
          seattle_antenna_types
      ),
      rf_source_z_is_relative_to_terrain => FALSE,
      geographic_coords => FALSE,
      bin_dim_meters => 2.0,
      assumed_receiver_height_agl => 2.0,
      max_ray_travel_meters => 2500,
      initial_rays_per_source => 64,
      rays_per_bin_autosplit_threshold => 1.5,
      min_receiver_signal_strength_dbm => -130.0,
      default_source_height_agl_meters => 20.0,
      ray_step_bin_multiple => 1.0,
      loop_grain_size => 8
    )
  )

Output of RF Propagation for Seattle using HeavyRF Omniverse integration

tf_rf_prop_max_signal (Isotropic Antennas)

SELECT * FROM TABLE(
   tf_rf_prop(
      rf_sources => CURSOR(
         SELECT 
            rf_source_id, x, y, z_meters
      ),
      rf_source_z_is_relative_to_terrain, 
      rf_source_signal_strength_dbm, 
      rf_source_signal_frequency_mhz   
      terrain => CURSOR(
         SELECT 
            x, y, elevation_amsl_meters
      ),
      geographic_coords,
      bin_dim_meters, 
      max_ray_travel_meters, 
      num_rays_per_source, 
      min_receiver_signal_strength_dbm,
      default_source_height_agl_meters,
      ray_step_bin_multiple,
      loop_grain_size
   )
)

Taking a set of point elevations and a set of signal source locations as input, tf_rf_prop_max_signal executes line-of-sight 2.5D RF signal propagation from the provided sources over a binned 2.5D elevation grid derived from the provided point locations, calculating the max signal in dBm at each grid cell, using the formula for free-space power loss. The RF source ID contributing the strongest signal is also outputted.

For the short version, where geographic_coords defaults to true, or for the long version where geographic_coords is explicitly set to true, x and y input coordinates are assumed to be lon/lat degrees. A best-fit conversion to a meters coordinate system is executed using the change in meters per lon/lat degree at the centroid of the input terrain, using the haversine distance formula. For convenience and optimal performance, tf_rf_prop_max_signal enables filter push-down by default, such that filters on the outputs rf_source_id, x, y, and elevation_amsl_meters are pushed down to the respective inputs in the rf_sources and terrain_elevations cursor subqueries.

Short Version

Input Arguments

Parameter	Details	Data Type
RF sources	Consists of rf_source_id, x (RF sources), y (RF sources), and z_meters.	CURSOR
rf_source_id	ID of the RF source. Used in the output for each grid cell to denote the RF source contributing the strongest signal.	Column<INT | BIGINT | TEXT ENCODING DICT>
x (RF sources)	x-coordinate of the RF source, assumed to be in longitude degrees. Whether FLOAT or DOUBLE, x and y must be the same type.	Column<FLOAT | DOUBLE>
y (RF sources)	y-coordinate of the RF source, assumed to be in latitude degrees. Whether FLOAT or DOUBLE, x and y must be the same type.	Column<FLOAT | DOUBLE>
z_meters	z-coordinate of the RF source, in meters. If rf_source_is_relative_to_terrain is set to true, meters are relative to the terrain height; for example, an input of 20 is 20 meters above ground level. Otherwise, it is absolute height above sea level; 20 is 20 meters above mean sea level (AMSL).	Column<FLOAT | DOUBLE>
rf_source_z_is_relative_to_terrain	true specifies that z_meters values are the height in meters above ground level. false indicates the values are height in meters above sea level.	BOOLEAN
rf_source_signal_strength_dbm	Signal strength in dBm for all RF sources.	DOUBLE
rf_source_signal_frequency_mhz	Frequency in MHZ of the RF sources.	DOUBLE
Terrain elevations	Consists of x (terrain elevations), y (terrain elevations), and elevation_amsl_meters.	CURSOR
x (terrain elevations)	x-coordinate of the terrain/building height, assumed to be in longitude degrees. Whether FLOAT or DOUBLE, x and y must be the same type.	Column<FLOAT | DOUBLE>
y (terrain elevations)	y-coordinate of the terrain/building height, assumed to be in latitude degrees. Whether FLOAT or DOUBLE, x and y must be the same type.	Column<FLOAT | DOUBLE>
elevation_amsl_meters	Elevation of the point, in meters above sea level.	Column<FLOAT | DOUBLE>
geographic_coords	true specifies that the input x and y arguments for RF sources and terrain elevations are in lon/lat degrees. false specifies that the data is already in a local meter coordinate system.	BOOLEAN
bin_dim_meters	Width and height of each binned terrain cell, which is the unit of granularity over which the RF propagation algorithm is executed.	DOUBLE
max_ray_travel_meters	Maximum meters for which to model RF propagation from any given source. Lower values can increase performance, but potentially misses the strongest repeater for a terrain cell that is further away than the value set.	DOUBLE
num_rays_per_source	Number of 2.5D rays to propagate from each source. Higher numbers potentially provide more accurate results but can decrease performance.	BIGINT
min_receiver_signal_strength_dbm	The minimum signal strength threshold in dBm to continue propagating a signal ray from a source. Rays stop being propagated when either the distance from the source exceeds the limit set by max_ray_travel_meters, or the signal strength (as measured by free-space power loss, assuming no obstructions in the path) drops below the value set by min_receiver_signal_strength_dbm.	DOUBLE

Outputs

A table of grid cells of width and height bin_dim_meters along with the maximum signal strength from any one repeater at that cell, and the ID of the repeater with the strongest signal.

Parameter	Details
x	x-centroid of the output bin, in lon/lat degrees.	Column<FLOAT | DOUBLE> (same type as RF sources input)
y	y-centroid of the output bin, in lon/lat degrees.	Column<FLOAT | DOUBLE>(same type as RF sources input)
elevation_amsl_meters	Maximum elevation of all input terrain data falling in the output bin, in meters above sea level.	Column<FLOAT | DOUBLE> (same type as terrain elevations input)
rf_source_id	ID of the repeater with the strongest signal for the grid cell.	Column<FLOAT | DOUBLE>(same type as RF sources ID input)
max_signal_strength_dbm	The maximum signal strength in dBm for a given terrain bin.	Column<FLOAT | DOUBLE> (same type as RF sources coordinates input)

Long Version

Input Arguments

Parameter	Details
RF sources	Consists of rf_source_id, x (RF sources), y (RF sources), and z_meters.	CURSOR
rf_source_id	ID of the RF source. Used in the output for each grid cell to denote the RF source contributing the strongest signal.	INT | BIGINT | TEXT ENCODING DICT
x (RF sources)	x-coordinate of the RF source. If geographic_coords is set to true, assumed to be longitude degrees; otherwise, an arbitrary meters-coordinate system. Whether FLOAT or DOUBLE, x and y must be the same type.	FLOAT | DOUBLE
y (RF sources)	y-coordinate of the RF source. If geographic_coords is set to true, assumed to be latitude degrees; otherwise, an arbitrary meters-coordinate system. Whether FLOAT or DOUBLE, x and y must be the same type.	FLOAT | DOUBLE
z_meters	z-coordinate of the RF source, in meters. If rf_source_is_relative_to_terrain is set to true, meters are relative to the terrain height; for example, an input of 20 is 20 meters above ground level. Otherwise, it is absolute height above sea level; 20 is 20 meters above mean sea level (AMSL).	FLOAT | DOUBLE
rf_source_z_is_relative_to_terrain	true specifies that z_meters values are the height in meters above ground level. false indicates the values are height in meters above sea level.	BOOLEAN
rf_source_signal_strength_dbm	Signal strength in dBm for all RF sources.	DOUBLE
rf_source_signal_frequency_mhz	Frequency in MHZ of the RF sources.	DOUBLE
Terrain elevations	Consists of x (terrain elevations), y (terrain elevations), and elevation_amsl_meters.	CURSOR
x (terrain elevations)	x-coordinate of the terrain/building height. If geographic_coords is set to true, assumed to be longitude degrees; otherwise, an arbitrary meters-coordinate system. Whether FLOAT or DOUBLE, x and y must be the same type.	FLOAT | DOUBLE
y (terrain elevations)	y-coordinate of the terrain/building height. If geographic_coords is set to true, assumed to be latitude degrees; otherwise, an arbitrary meters-coordinate system. Whether FLOAT or DOUBLE, x and y must be the same type.	FLOAT | DOUBLE
elevation_amsl_meters	Elevation of the point, in meters above sea level.	FLOAT | DOUBLE
geographic_coords	true specifies that the input x and y arguments for RF sources and terrain elevations are in lon/lat degrees. false specifies that the data is already in a local meter coordinate system.	BOOLEAN
bin_dim_meters	Width and height of each binned terrain cell, which is the unit of granularity over which the RF propagation algorithm is executed.	DOUBLE
max_ray_travel_meters	Maximum meters for which to model RF propagation from any given source. Lower values can increase performance, but potentially misses the strongest repeater for a terrain cell that is further away than the value set.	DOUBLE
num_rays_per_source	Number of 2.5D rays to propagate from each source. Higher numbers potentially provide more accurate results but can decrease performance.	BIGINT
min_receiver_signal_strength_dbm	The minimum signal strength threshold in dBm to continue propagating a signal ray from a source. Rays stop being propagated when either the distance from the source exceeds the limit set by max_ray_travel_meters, or the signal strength (as measured by free-space power loss, assuming no obstructions in the path) drops below the value set by min_receiver_signal_strength_dbm.	DOUBLE
default_source_height_agl_meters	The default height in meters above ground level for a source if there is no input data in the terrain_elevations for the terrain bin in which a given rf_source lies.	DOUBLE
ray_step_bin_multiple	The step used in number of bins (can be fractional) for the RF propagation simulation. Lower values of this (below 1.0) can increase accuracy of the simulation, but decrease performance. Values above 1.0 are not recommended because they can cause gaps in the output.	DOUBLE
loop_grain_size	The size in number of rays at which to parallelize over; threads will process rays in groups of at least this size. The default value is 40; performance may improve by changing this number, depending on hardware setup.	BIGINT

Output Columns

A table of grid cells of width and height bin_dim_meters along with the maximum signal strength from any one repeater at that cell, and the ID of the repeater with the strongest signal.

Parameter	Type	Details
x		x-centroid of the output bin, in lon/lat degrees.	FLOAT | DOUBLE (same type as RF sources input)
y		y-centroid of the output bin, in lon/lat degrees.	FLOAT | DOUBLE(same type as RF sources input)
elevation_amsl_meters		Maximum elevation of all input terrain data falling in the output bin, in meters above sea level.	FLOAT | DOUBLE (same type as terrain elevations input)
rf_source_id		ID of the repeater with the strongest signal for the grid cell.	FLOAT | DOUBLE(same type as RF sources ID input)
max_signal_strength_dbm		The maximum signal strength in dBm for a given terrain bin.	FLOAT | DOUBLE (same type as RF sources coordinates input)

tf_rf_prop

Used for generating top-k signals where 'k' represents the maximum number of antennas to consider at each geographic location. The full relevant parameter name is strongest_k_sources_per_terrain_bin. For example, if k is set to 3, the function will return up to three overlapping antenna signals based on their strength. In that case, if only 2 signals are present, they will be returned. and if 5 signals are actually present, only the strongest 3 will be recorded.

This version of the RF function can be used in optimizing antenna placements use cases or to minimize interference. For example, you might simulate repeater antenna placements on every lampost across an area, but then only plan to keep the top-performing ones. By allowing overlaps in the initial simulation, you avoid intrpducing coverage gaps when dropping out antennas, while also avoiding the requirement of multiple simulations.

SELECT * FROM TABLE(
   tf_rf_prop(
      data => CURSOR(
         SELECT 
            rf_source_id, x, y, repeater_height_meters
      ),
      rf_source_z_is_relative_to_terrain, 
      rf_source_signal_strength_dbm, 
      rf_source_signal_frequency_mhz   
      data => CURSOR(
         SELECT 
            x, y, elevation_amsl_meters
      ),
      bin_dim_meters, 
      strongest_k_sources_per_terrain_bin
      max_ray_travel_meters, 
      num_rays_per_source, 
      min_receiver_signal_strength_dbm
      default_source_height_agl_meters
      ray_step_bin_multiple
      loop_grain_size
   )
)

Short Version

Input Arguments

Parameter	Details	Data Type
rf_sources	Consists of rf_source_id, x (RF sources), y (RF sources), and z_meters.	CURSOR
rf_source_id	ID of the RF source. Used in the output for each grid cell to denote the RF source contributing the strongest signal.	Column<INT | BIGINT | TEXT ENCODING DICT
x (RF sources)	x-coordinate of the RF source, assumed to be in longitude degrees. Whether FLOAT or DOUBLE, x and y must be the same type.	Column<FLOAT | DOUBLE>
y (RF sources)	y-coordinate of the RF source, assumed to be in latitude degrees. Whether FLOAT or DOUBLE, x and y must be the same type.	Column<FLOAT | DOUBLE>
repeater_height_meters	.	Column<FLOAT | DOUBLE>
rf_source_z_is_relative_to_terrain	true specifies that z_meters values are the height in meters above ground level. false indicates the values are height in meters above sea level.	BOOLEAN
rf_source_signal_strength_dbm	Signal strength in dBm for all RF sources.	DOUBLE
rf_source_signal_frequency_mhz	Frequency in MHZ of the RF sources.	DOUBLE
Terrain elevations	Consists of x (terrain elevations), y (terrain elevations), and elevation_amsl_meters.	CURSOR
x (terrain elevations)	x-coordinate of the terrain/building height, assumed to be in longitude degrees. Whether FLOAT or DOUBLE, x and y must be the same type.	Column<FLOAT | DOUBLE>
y (terrain elevations)	y-coordinate of the terrain/building height, assumed to be in latitude degrees. Whether FLOAT or DOUBLE, x and y must be the same type.	Column<FLOAT | DOUBLE>
elevation_amsl_meters	Elevation of the point, in meters above sea level.	Column<FLOAT | DOUBLE>
bin_dim_meters	Width and height of each binned terrain cell, which is the unit of granularity over which the RF propagation algorithm is executed.	DOUBLE
num_top_sources_per_terrain_bin	Number of best sources ranked by signal strength for a terrain bin to be outputted in the results.	BIGINT
max_ray_travel_meters	Maximum meters for which to model RF propagation from any given source. Lower values can increase performance, buy potentially misses the strongest repeater for a terrain cell that is further away than the value set.	DOUBLE
num_rays_per_source	Number of 2.5D rays to propagate from each source. Higher numbers potentially provide more accurate results but can decrease performance.	BIGINT
min_receiver_signal_strength_dbm	The minimum signal strength threshold in dBm to continue propagating a signal ray from a source. Rays stop being propagated when either the distance from the source exceeds the limit set by max_ray_travel_meters, or the signal strength (as measured by free-space power loss, assuming no obstructions in the path) drops below the value set by min_receiver_signal_strength_dbm.	DOUBLE

Outputs

A table of grid cells of width and height bin_dim_meters along with the maximum signal strength from any one repeater at that cell, and the ID of the repeater with the strongest signal.

Parameter	Details
terrain_bin_id
x	x-centroid of the output bin, in lon/lat degrees.	Column<FLOAT | DOUBLE> (same type as RF sources input)
y	y-centroid of the output bin, in lon/lat degrees.	Column<FLOAT | DOUBLE>(same type as RF sources input)
elevation_amsl_meters	Maximum elevation of all input terrain data falling in the output bin, in meters above sea level.	Column<FLOAT | DOUBLE> (same type as terrain elevations input)
rf_source_id	ID of the repeater with the strongest signal for the grid cell.	Column<FLOAT | DOUBLE>(same type as RF sources ID input)
rf_signal_strength_dbm	The signal strength in dBm for a given terrain bin.	Column<FLOAT | DOUBLE> (same type as RF sources coordinates input)
rf_signal_z_angle_degrees	The angle in degrees of the output bin with respect to the top-k signal source rf_source_id.	Column<FLOAT | DOUBLE> (same type as RF sources coordinates input)
rf_source_distance_meters	The distance of the top-k signal source rf_source_id from the output bin, in meters.	Column<FLOAT | DOUBLE> (same type as RF sources coordinates input)

Long Version

Input Arguments

Parameter	Details	Data Type
RF sources	Consists of rf_source_id, x (RF sources), y (RF sources), and z_meters.	CURSOR
rf_source_id	ID of the RF source. Used in the output for each grid cell to denote the RF source contributing the strongest signal.	INT | BIGINT | TEXT ENCODING DICT
x (RF sources)	x-coordinate of the RF source. If geographic_coords is set to true, assumed to be longitude degrees; otherwise, an arbitrary meters-coordinate system. Whether FLOAT or DOUBLE, x and y must be the same type.	FLOAT | DOUBLE
y (RF sources)	y-coordinate of the RF source. If geographic_coords is set to true, assumed to be latitude degrees; otherwise, an arbitrary meters-coordinate system. Whether FLOAT or DOUBLE, x and y must be the same type.	FLOAT | DOUBLE
repeater_height_meters		FLOAT | DOUBLE
rf_source_z_is_relative_to_terrain	true specifies that z_meters values are the height in meters above ground level. false indicates the values are height in meters above sea level.	BOOLEAN
rf_source_signal_strength_dbm	Signal strength in dBm for all RF sources.	DOUBLE
rf_source_signal_frequency_mhz	Frequency in MHZ of the RF sources.	DOUBLE
Terrain elevations	Consists of x (terrain elevations), y (terrain elevations), and elevation_amsl_meters.	CURSOR
x (terrain elevations)	x-coordinate of the terrain/building height. If geographic_coords is set to true, assumed to be longitude degrees; otherwise, an arbitrary meters-coordinate system. Whether FLOAT or DOUBLE, x and y must be the same type.	FLOAT | DOUBLE
y (terrain elevations)	y-coordinate of the terrain/building height. If geographic_coords is set to true, assumed to be latitude degrees; otherwise, an arbitrary meters-coordinate system. Whether FLOAT or DOUBLE, x and y must be the same type.	FLOAT | DOUBLE
elevation_amsl_meters	Elevation of the point, in meters above sea level.	FLOAT | DOUBLE
bin_dim_meters	Width and height of each binned terrain cell, which is the unit of granularity over which the RF propagation algorithm is executed.	DOUBLE
strongest_k_sources_per_terrain_bin
max_ray_travel_meters	Maximum meters for which to model RF propagation from any given source. Lower values can increase performance, but potentially misses the strongest repeater for a terrain cell that is further away than the value set.	DOUBLE
num_rays_per_source	Number of 2.5D rays to propagate from each source. Higher numbers potentially provide more accurate results but can decrease performance.	BIGINT
min_receiver_signal_strength_dbm	The minimum signal strength threshold in dBm to continue propagating a signal ray from a source. Rays stop being propagated when either the distance from the source exceeds the limit set by max_ray_travel_meters, or the signal strength (as measured by free-space power loss, assuming no obstructions in the path) drops below the value set by min_receiver_signal_strength_dbm.	DOUBLE
default_source_height_agl_meters	The default height in meters above ground level for a source if there is no input data in the terrain_elevations for the terrain bin in which a given rf_source lies.	DOUBLE
ray_step_bin_multiple	The step used in number of bins (can be fractional) for the RF propagation simulation. Lower values of this (below 1.0) can increase accuracy of the simulation, but decrease performance. Values above 1.0 are not recommended because they can cause gaps in the output.	DOUBLE
loop_grain_size	The size in number of rays at which to parallelize over; threads will process rays in groups of at least this size. The default value is 40; performance may improve by changing this number, depending on hardware setup.	BIGINT

Outputs

A table of grid cells of width and height bin_dim_meters along with the maximum signal strength from any one repeater at that cell, and the ID of the repeater with the strongest signal.

Parameter	Details	Data Type
terrain_bin_id
x	x-centroid of the output bin, in lon/lat degrees.	FLOAT | DOUBLE (same type as RF sources input)
y	y-centroid of the output bin, in lon/lat degrees.	FLOAT | DOUBLE(same type as RF sources input)
elevation_amsl_meters	Maximum elevation of all input terrain data falling in the output bin, in meters above sea level.	FLOAT | DOUBLE (same type as terrain elevations input)
rf_source_id	ID of the repeater with the strongest signal for the grid cell.	FLOAT | DOUBLE(same type as RF sources ID input)
rf_signal_strength_dbm	The signal strength in dBm for a given terrain bin.	FLOAT | DOUBLE (same type as RF sources coordinates input)
rf_signal_z_angle_degrees
rf_source_distance_meters