Package: owlet
A Geospatial Python Package for Field ResearchersOwlet and EGF: Developed for Field ResearchersOwlet is a Python library for interacting with and mapping EGF files.EGF, or Exact Geometry Format, is a file structure designed specifically for recording geo-data without traditional GIS software. An EGF file contains all of the necessary components required to define geospatial features— without overcomplicating it.EGF File ExampleOverviewAn EGF file is comprised of three sections:A Feature Type Declaration(point, line, polygon)Attribute HeadersFeatures: attributes & coordinate setsExample EFG file containing two placemarks:PT



Park Name, City, Pond, Fountain



Post office Square, Boston, FALSE, TRUE
42.356243, -71.055631, 2



Boston Common, Boston, TRUE, TRUE
42.355465, -71.066412, 10In an EGF file, each section / feature is separated by three blank lines and the file ends with a single blank line.An EGF file is a '.txt' file renamed to '.egf'Full EGF DocumentationInstalling OwletTo install owlet, type one of the following commands into the terminal or command lineWindows>>>py-mpipinstallowletMacOS / Linux>>>pip3installowletUsing OwletTo begin, save the EGF file example above to your computer asBostonParks.egfusing a text editor such as Notepad.Once the EGF file is saved, create a new Python file and import Owlet.When writing a new Python file, begin by importing Owlet.importowletReading an EGF fileTo read an EGF file, begin by saving the path of the EGF file to a variable in your python script.Then pass the variable that hold the EGF file's path to theread_egf()function. Since theread_egf()function is a part of the Owlet Python package, the function is called by typingowlet.before the function name - e.g.owlet.read_egf()Below, the EGF file is loaded and saved to a variable namedmy_shape.in_file="path/to/file/BostonParks.egf"my_shape=owlet.read_egf(in_file)If the file path is short, it may be easier to pass the path directly in to the function like in the example below. For longer paths, it is neater to save the path to a variable.my_shape=owlet.read_egf("folder/BostonParks.egf")Visualizing an EGF fileTo visualizemy_shape, call thevisualize()function and passmy_shapeto it.owlet.visualize(my_shape)Uponvisualize()being executed, the computer's default web browser will open and provide a preview ofmy_shapeusing the webpagegeojson.ioBoth points from the EGF file are displayed on the map after runningowlet.visualize(my_shape)EGF Files also support linestrings for mapping pathsPolygons are also supported by EGFConverting an EGF File to Other FormatsTo interact with the data from an EGF file outside of Owlet, the data can be exported to a different format. Owlet offers a few different export options.GeoJSONTo use the EGF data with other GIS software packages, Owlet provides a GeoJSON export option.To export data in GeoJSON format, first save the export file path to a variable. (Notice that the new file's name and file extension are included in the path.)Then call the functionwrite_geojson()and pass it the path of the file to be created as well as the variable that holds the EGF geometry.out_file="folder/MyShape.json"owlet.write_geojson(out_file,my_shape)Uponwrite_geojson()being executed, a.jsonfile will be created at the location specified by the path defined by theout_filevariable. The new GeoJSON file can be loaded, viewed, and manipulated by many common GIS programs.Loading GeoJSON into Owletin_file="path/to/file/MyShape.json"my_shape=owlet.read_geojson(in_file)Note:Owlet has the ability to read GeoJSON files where each feature is of the same geometry type and every feature is contained within a "FeatureClass" (QGIS exports GeoJSON files in this format). Owlet supports Point, LineString, and Polygon GeoJSON features only. A GeoJSON file may have either.jsonor.geojsonas its file extension.Reading an EGF file and Writing it to a GeoJson File - Complete Scriptimportowletin_file="path/to/file/BostonParks.egf"out_file="folder/MyShape.json"my_shape=owlet.read_egf(in_file)owlet.write_geojson(out_file,my_shape)CSVTo view/manipulate an EGF file in as a table, thewrite_csv()function can be used in the same way as thewrite_geojson()function.To export data in CSV format, first save the export file path to a variable. (Notice that the new file's name and file extension are included in the path.)Then call the functionwrite_csv()and pass it the path of the file to be created as well as the variable that holds the EGF geometry.out_file="folder/MyShape.csv"owlet.write_csv(out_file,my_shape)The resulting CSV file will match the table below:Park NameCityPondFountainGEOMETRY_PTPost office SquareBostonFALSETRUE[-71.055631, 42.356243, 2.0]Boston CommonBostonTRUETRUE[-71.066412, 42.355465, 10.0]When saved as a CSV file and opened with an appropriate program, the data can be filtered, new attributes can be added, and existing attributes can be edited.For example, aStateattribute could be added to each record of the table.Park NameCityStatePondFountainGEOMETRY_PTPost office SquareBostonMAFALSETRUE[-71.055631, 42.356243, 2.0]Boston CommonBostonMATRUETRUE[-71.066412, 42.355465, 10.0]As long as theGEOMETRY_PTcolumn is not manipulated, the CSV file can be loaded back in to Owlet.Loading CSV into Owletin_file="path/to/file/MyShape.csv"my_shape=owlet.read_csv(in_file)To see that the changes made to the table have been reflected in Owlet, use theprint()function.print(my_shape)Which will print out:'PT' GCA object containing 2 feature(s) with the following attributes: ['Park Name', 'City', 'State', 'Pond', 'Fountain']The above line reveals thatmy_shapeis aPT(Point) file that contains2 featuresthat each havePark Name, City, State, Pond,andFountainas attributes."GCA object" refers to the internal format that Owlet uses to store geometry.Reading an EGF file and Writing it to a CSV File - Complete Scriptimportowletin_file="path/to/file/BostonParks.egf"out_file="folder/MyShape.csv"my_shape=owlet.read_egf(in_file)owlet.write_csv(out_file,my_shape)Google Earth KMLOwlet can also write KML files for use with Google Earth. Owlet leverages the KML format's "ExtendedData" feature which makes Owlet's KMLs import cleanly into QGIS.Thewrite_kml()function takes multiple arguments:Path of file to writeEGF to write(the variable that an EGF file is saved to)Title of the attribute column that contains the attributes that the features should be named withName of folder within KML file that will contain the features of the EGF fileFolder description (optional)Altitude mode (optional)Optional arguments do not need to be defined in order for a KML to be produced.Owlet accepts three types of altitude modes:'ctg'short for Clamped to Ground. Elevation values are ignored and all features are displayed at ground level.'rtg'short for Relative to Ground. Elevation values are rendered as "x" meters above the ground below.'abs'short for Absolute. Elevation values are rendered as "x" meters above mean sea level.The default altitude mode isctgWrite a KML file by only providing the required argumentsout_file="folder/MyShape.kml"owlet.write_kml(out_file,my_shape,'Park Name','Parks')Adding a Folder Descriptionout_file="folder/MyShape.kml"owlet.write_kml(out_file,my_shape,'Park Name','Parks','Parks near Downtown Boston')Changing the Altitude Modeout_file="folder/MyShape.kml"owlet.write_kml(out_file,my_shape,'Park Name','Parks',altitude_mode='rtg')Providing all KML Argumentsout_file="folder/MyShape.kml"owlet.write_kml(out_file,my_shape,'Park Name','Parks','Parks near Downtown Boston','rtg')Reading an EGF file and Writing it to a KML File - Complete Scriptimportowletin_file="path/to/file/BostonParks.egf"out_file="folder/MyShape.kml"my_shape=owlet.read_egf(in_file)owlet.write_kml(out_file,my_shape,'Park Name','Parks','Parks near Downtown Boston','rtg')EGFOwlet will also export to EGF.out_file="folder/MyShape.egf"owlet.write_egf(out_file,my_shape)Owlet License:GNU GPLv3