Introducing the GeoLabAPI
The GeoLabAPI (GeoLab "Application Programming Interface") is a powerful component for GeoLabPX5. You use it to access the services of GeoLab from within your own program, using your favorite programming or scripting language.
The following diagram gives a general overview of how the GeoLabAPI is structured. Note that the GeoLabAPI is a component of GeoLabPX5, 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.
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 "Acme" in your "IN" command file, you would create your file with the name "Acmeglcmd.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 GeoLabPX5, 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 GeoLabPX5. When you place this file in GeoLabPX5's installation folder, GeoLabPX5 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:\GeoLabPX5\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 GeoLabPX5'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:\GeoLabPX5\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 GeoLabPX5:
- A GeoLabPX5 license, version 5.7.1 minimum. All licensing is handled in GeoLabPX5's Licensing dialog (Project/Tools/Licensing...). To request a GeoLabPX5 license, you use the controls in the "Online Licensing" tab.
- A GeoLabAPI license, version 5.7.1 minimum, which you must request from the "API Licensing" tab.
- Create your GeoLabAPI "IN" command file, named as described above (*glcmd.txt).
- When you wish to run your command file, first run GeoLabPX5, then, with the Project/Setup tab still active, copy your command file to your installed GeoLabPX5 folder. Note that you should copy the command file to your GeoLabPX5 folder, not move it, so that you retain a copy in case you have to edit it and/or run it again.
- In GeoLabPX5, 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 finally 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.
Note that the GeoLabAPI functions as described above only when it is licensed.
What new commands will you need in the GeoLabAPI? Just let us know.