GeoLab API INTEGRATION

Morning Sun shining over city scape
Drone flying over road

​The GeoLabAPI (GeoLab "Application Programming Interface") is a powerful component for GeoLab. You use it to access the services of GeoLab from within your own program, using your favorite programming or scripting language.

The GeoLabAPI provides you with a powerful tool for automatically making use of GeoLab’s powerful adjustments from within your own software product, using a programming or scripting language of your choice.

The following diagram gives a general overview of how the GeoLabAPI is structured. Note that the GeoLabAPI is a component of GeoLab2020, so it has full access to services in GeoLab. Initially, we have focused on the services described below, but the potential for many more services is large.

GEOLab API Screenshot

​In the diagram, "YourApp" represents your application, the program you wrote, and when you wish to adjust a network (or use one of the other GeoLabAPI commands available), you simply create a special input text file (full details are provided below).
​
​The input text file "IN", created by you, contains special "commands" (specially formatted lines of text as described below). The IOB and LST are GeoLab's regular input IOB (Input OBservations) file and output LST (LiSTing) file.

The "IN" file's filename must be in the form: *glcmd.txt, in which you must replace the * with your unique text identifier. For example, if you wish to use the text ID "GPSNet_" in your "IN" command file, you would create your file with the name "GPSNet_glcmd.txt". After you create this file, you simply add special command text lines to it as described below.

In summary, the various items in the diagram above depict the following:

IOB: When you create your "IN" command file, you supply the path and filename for your IOB file if you wish to do an adjustment (see GlApi_AdjNetwork).

LST: When you use the GeoLabAPI to do an adjustment, a LST file is produced by GeoLab2020, which is GeoLab's output listing report on the processing you requested.

OUT: The OUT file is created by the GeoLabAPI and is used to provide you with any messages related to the processing you requested using the GeoLabAPI. The OUT file may contain zero or more messages. The OUT file is named *glend.txt, where * is the same ID mentioned above for the IN filename. As a signal that the processing of your IN file has been completed, the OUT file is created even when there are no messages to write to it. You should delete your OUT file after noting any messages it contains.

IN: This file was described above as containing all commands you wish to submit to GeoLab2020. When you place this file in GeoLab2020's installation folder, GeoLab2020 and the GeoLabAPI will detect, load, and delete this file, after which it will process all commands in the file.

The following text commands are currently allowed in your "*glcmd.txt" command file (all in comma-separated variable format - see examples below):

GlApi_AdjNetwork, mainIOBPathAndFilename: Sets up and processes the adjustment of the network with the specified main IOB file in the specified project folder. This command does the same thing as the Assistant tab's "Process main IOB" button, so you must also ensure that the options desired for the adjustment are preset in the Setup tab's "Edit default options..." button.
Example: GlApi_AdjNetwork, C:\GeoLab2020\GLProjs\GPS Net Sample\gpsnet.iob

GlApi_SetCOMP, mode: Sets GeoLab's computation mode to ADJ (adjustment) if mode is 1, or to SIM (simulation) if mode is 0. Also see the COMP record type.
Example: GlApi_SetCOMP, 1

GlApi_SetHmpConfidenceLevel, percentConfLevel: Sets the "horizontal mid point" (HMP) confidence level, with a floating point value from 10 to 99.999 percent. Also see the HCLV record type.
Example: GlApi_SetHmpConfidenceLevel, 95.0

GlApi_SetHmpFromToStations, fromStationName, toStationName: Sets the from-station and to-station of an existing network line for which a horizontal mid point error ellipse is to be calculated. Also see the HCMP record type. The fromStationName and toStationName variables must specify the names of stations in the network.
Example: GlApi_SetHmpFromToStations, StationA, StationB

GlApi_SetPADJ, neo, neh, plo, plh, xyz, aux, sfmc, gridDistAzim: Sets GeoLab's PADJ record options - please see the PADJ record for more information. This command controls which adjusted values are listed in GeoLab2020's output listing (LST) file.

Example: GlApi_SetPADJ, 1, 0, 0, 1, 0, 0, 1, 0

GlApi_SetPGEO, print: Sets GeoLab's PGEO record options - please see the PGEO record for more information. Example:
Example: GlApi_SetPGEO, 1

GlApi_SetPSOL, enable, allPasses: Sets GeoLab's PSOL record options - please see the PSOL record type for more information.
Example: GlApi_SetPSOL, 1

GlApi_SetPMIS, firstPass, subsequentPasses: Sets GeoLab's PMIS record options - please see that record type for more information.
Example: GlApi_SetPMIS, 1, 1

GlApi_SetPRES, enable, rejectsOnly: Sets GeoLab's PRES record options - please see that record type for more information.
Example: GlApi_SetPRES, 1, 0

GlApi_SetPrintReliability, external, internal: Sets the options for listing external and internal reliability values. The external and internal parameters must evaluate to bool values of true and false. For example, the line "GlApi_SetPrintReliability, 1, 1" (without the quotes) turns both external and internal on. Also see the PREL record type.
Example: GlApi_SetPrintReliability, 0, 0

GlApi_SimNetwork, mainIOBPathAndFilename: Sets up and processes the simulation (preanalysis) of the network with the specified main IOB file in the specified project folder.
Example: GlApi_SimNetwork, C:\GeoLab2020\GLProjs\GPS Net Sample\gpsnet.iob

As you can see, all lines of text in the "IN" file must be in comma-separated variable (CSV) format.

Please note that the following are required to use the GeoLabAPI with GeoLab:

  1. A GeoLab2020 license. All licensing is handled in GeoLab's Licensing dialog (Project/Tools/Licensing...). To request a GeoLab2020 license, you use the controls in the "Online Licensing" tab.

  2. A GeoLabAPI license, which you must request from the same licensing tab as above.

  3. Create your GeoLabAPI "IN" command file, named as described above (*glcmd.txt).

  4. When you wish to run your command file, first run GeoLab, then, with the Project/Setup tab active, copy your command file to your installed GeoLab folder. Note that you should copy the command file to your GeoLab2020 folder, not move it, so that you retain a copy in case you have to edit it and/or run it again.

  5. In GeoLab, click the "Assistant" tab, and ensure that the "GeoLabAPI" checkbox is checked. Note that the GeoLabAPI will not process command files unless the Assistant tab is open, and the "GeoLabAPI" checkbox is checked. With all of this set properly, the GeoLabAPI will check for a command file every several seconds, and when it finds one, it will load it, delete it, and process the commands it contained.


Also note that the GeoLabAPI must use SmartAdjust when it adjusts your networks, which it will do whether you have the SmartAdjust checkbox checked or not. If you check the Assistant tab's SmartAdjust checkbox, SmartAdjust will be used when you manually run an adjustment by clicking the "Process main IOB" button in the Assistant. The GeoLabAPI needs the services of SmartAdjust in order to handle the process of commenting-out flagged residuals correctly.

In this way, you can automate your adjustments and statistical analyses, even in real time robotic surveys, or with high-accuracy navigation, when your survey accuracy needs improvement, just add more measurements and re-adjust, in real time of course.