Input Files

This page introduces the input files used in a Terragraph network plan, including required files and optional files.

The table below describes all the input files, with its supported file formats and parameter name in the YAML file. Further details are provided in each corresponding section.

File Type	Required or Optional	Functionality	Supported Formats	Parameter Field(s)
Boundary Polygon File	Required	Boundary of the AOI	KML/KMZ	BOUNDARY_POLYGON_FILE_PATH
GeoTIFF Files	Optional, but recommend for better accuracy	Surface elevation data	TIF	DSM_FILE_PATHS, DTM_FILE_PATH, DHM_FLE_PATH
User Input Site File	Optional	User-specified site locations	KML/KMZ, CSV	SITE_FILE_PATH
Building Outline File	Optional, used for Automatic Site Detection	Building outlines	KML/KMZ, zipped shape file	BUILDING_OUTLINE_FILE_PATH
Candidate Topology File	Required for an optimization-only plan	Candidate network topology to optimize	KML/KMZ	CANDIDATE_TOPOLOGY_FILE_PATH
Base Topology File	Optional, used for Extend Base Topology	Base network topology to extend	KML/KMZ	BASE_TOPOLOGY_FILE_PATH

The input files can be generated by a GIS tool, such as Google Earth and QGIS, and some of them can be obtained by the planner tool itself.

Boundary Polygon File

A boundary polygon file is a KML/KMZ file defining the boundary or area of interest (AOI) of the network plan.

Requirements

1. There should be exactly one Polygon geometry in the KML/KMZ file

GeoTIFF Files

GeoTIFF Files are files defining the elevation of the surface within the AOI. There are 3 kinds of GeoTIFF files used in the planner:

1. DSM: provides the elevation of the surface directly.
2. DTM: provides the elevation of the terrain.
3. DHM: provides the elevation of the height of construction, buildings or trees on the surface.

To get more accurate LOS results, please provide either DSM GeoTIFF File(s) or DTM and DHM together. If the latter combination is provided, the planner will form a DSM by adding the DHM to the DTM.

Requirements

1. The projection information and the coordinate reference system (CRS) should be correct.
2. There should be exactly one single raster band.
3. The data collection time should be within 20 years of the time the plan is run.
4. The linear units should be in meters.
5. The pixel size should between 0.15 meters and 35 meters.
6. The veritical projection system should be correct, if provided.

User Input Site File

The user input site file provides the location of user-provided POP, DN and CN sites, and can be either in KML/KMZ format or CSV format. All the sites in the file are considered to be candidate sites and will go through LOS checks.

Requirements

KML/KMZ

1. Put POP sites under a folder whose name contains the substring "POP". Do the same for DNs and CNs. Note: Do not have a parent folder with those substrings. Otherwise, all the sites under this parent folder are considered as that type of site.
2. Use a Point geometry for each site placemark.
3. Provide the information of the site via the data field.
4. The latitude and longitude are required, but the altitude is optional. When the altitude is not given, the planner uses MOUNTING_HEIGHT_ABOVE_ROOFTOP, DEFAULT_POP_HEIGHT_ON_POLE, DEFAULT_DN_HEIGHT_ON_POLE, or DEFAULT_CN_HEIGHT_ON_POLE to get the altitude based on the location type and site type.
5. If the altitude of a placemark is provided and the altitude mode is absolute, the altitude is considered as the absolute altitude over mean sea level; if the altitude of a placemark is provided and the altitude mode is relativeToGround, the altitude is considered as the relative height to the surface (DSM). Otherwise, the planner will infer the altitude using the defaults.

CSV

1. Only latitude and longitude columns are required. The same rules as those in KML/KMZ are used to infer the altitude. If the site_type is not provided for the user input site file, the site is considered a POP by default.

Site Attributes

Extra attributes can be specified via data fields for KML/KMZ input and columns for CSV input. The following table describes all the possible attributes.

Attribute	Acceptable Names
latitude	base_lat, latitude, lat
longitude	base_lon, longitude, lon
altitude	altitude, alt
height	height, install_height, site_height, height_m, height(m), height (m)
name	name, site_name, site name, pole_name
site_type	type, site_type, site type
device_sku	sku, device_sku, device sku
number_of_subscribers	number_of_demand_points, number of demand points, num_demand_points, number_of_subscribers, number of subscribers, number of demand sites, num_demand_sites, demand_points, demand points, demand_sites, demand sites
location_type	location type, location_type

1. All the Acceptable Names are case-insensitive
2. For KML/KMZ, device_sku, number_of_subscribers and location_type come from data fields; location attributes are from the coordinates of the placemarks; site_type is inferred from the folder name.
3. NOTE: If the name is provided, it must be unique.

Building Outline File

The building outline file describes the outline of the buildings in the AOI. The planner uses the outlines to detect the site locations automatically with the Automatic Site Detection feature.

The building outline file can be either in a zipped shapefile format or a KML/KMZ format.

Requirements

General

1. The projection information and the coordinate reference system (CRS) should be correct.
2. The veritical projection system should be correct, if provided.
3. All the building outlines are expected to be in the Polygon geometry type.

Shape file specific

In addition to the general rules, there are some extra rules if you are using zipped shape files.

1. All the files should be put at the top level of the zip file.
2. Only one .shp file, together with the corresponding .shx, .prj and dbf files, should be included in the zip file.

Candidate Topology File

The candidate topology file is only used in an optimization-only plan, and represents a network with all the sites and links.

The input candidate topology file can be either in a KML/KMZ format or a zipped file of two csv files. The Topology KML File from the output of a LOS plan can be re-used in the optimization plan directly.

Requirements

1. All the input folder names or column names are case-insensitive.

KML/KMZ

A KML/KMZ file can contain site, link, and demand site information.

1. Site
   1. All the rules in the KML/KMZ requirements in the User Input Site File section still apply.
   2. The status of the site can is parsed from the KML/KMZ input
      1. The status includes CANDIDATE, PROPOSED, EXISTING, UNAVAILABLE and UNREACHABLE. See more details at StatusType in enums.py
      2. To specify the status, please put the site folder under a parent folder with the status type. For instance, if you have a site in the folder structured as EXISTING -> DN -> site, the site is considered to be an existing DN in the network.
      3. If the status type is not specified, CANDIDATE will be used.
2. Link
   1. There are three different link types, which are WIRELESS_BACKHAUL, WIRELESS_ACCESS and ETHERNET. To input the links, place them under a folder with the link type as its name.
   2. Use a LineString geometry for each link.
   3. Provide the information of the link via the data field. You can provide TX_SITE_NAME and RX_SITE_NAME for each link to specify two end sites. If they are not provided, the planner will pick all the sites within 10 meters of the end of link as end sites.
   4. The rule 4 and 5 about altitude in the KML/KMZ requirements of User Input Site File section apply.
   5. All three status rules for sites are applied to links.
3. Demand Sites
   1. Demand sites allow the user to specify locations requiring connectivity.
   2. User-specified demand sites will only apply if ENABLE_MANUAL_DEMAND is set to True.
   3. You can provide the demand site in the network by providing Point placemarks under a Demand Sites folder in the KML/KMZ.
   4. The altitude information of the demand site is ignored.

Zipped CSV

The zip file should contain a sites.csv file and a links.csv file to provide the information of sites and links, respectively. Unlike KML/KMZ, user-specified demand sites are not supported.

1. Site

   All the site attributes from the table in the User Input Site File can be specified, but unlike a user input site file, there are 4 required attributes, which are latitude, longitude, site_type and name.

2. Link

   You only need to specify the names of the two end sites for each link, rather than the locations. There are three ways to specify them:

   1. A single SITE_PAIR column. The links should be specified in the {tx_site_name}-->{rx_site_name} format. These links are directed, so the reverse link must be provided if it is a backhaul link.
   2. A TX_SITE_NAME column and a RX_SITE_NAME column. These links are directed, so the reverse link must be provided if it is a backhaul link.
   3. A SITE1_NAME column and a SITE2_NAME column. In this case, the links in both directions are automatically added if it is a backhaul link.

   The following table shows the acceptable column names for each column type.

   Column Type	Acceptable Column Names
   SITE_PAIR	site_pair, sites
   TX_SITE_NAME	tx_site, tx_site_name, tx_site_id, from_site, from_site_name, from_site_id
   RX_STIE_NAME	rx_site, rx_site_name, rx_site_id, to_site, to_site_name, to_site_id
   SITE1_NAME	site1, site1_id, site1_name
   SITE2_NAME	site2, site2_id, site2_name

Base Topology File

The base topology file is similar to candidate topology file, but is used in an LOS Analysis plan or an End-to-End plan. All the sites and links in the file are considered EXISTING.