User Guide Station Design Toolbox
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 16
| Download | |
| Open PDF In Browser | View PDF |
STATION DESIGN TOOLBOX GUI USER GUIDE Kara M. Koetje & Margaret L. Palmsten U.S. Naval Research Laboratory, Stennis Space Center, MS Sediment Dynamics, Marine Geosciences Division 22 March 2019 CONTENTS EXECUTIVE SUMMARY 1. PURPOSE.......................................................................................................................................... E-1 2. SOFTWARE REQUIREMENTS AND DEPENDENCIES.................................................................. 1 3. USING THE STATION DESIGN TOOLBOX GUI ............................................................................ 2 4. INPUT ARGUMENTS.......................................................................................................................... 3 5. INPUT FILES ........................................................................................................................................ 4 6. DETERMINING EPSG CODE ............................................................................................................. 5 7. OUTPUT FILES AND RESULTS ........................................................................................................ 5 8. LIMITATIONS ..................................................................................................................................... 8 APPENDIX A: INSTALLING OPENEARTH TOOLBOX .................................................................... A-1 iii FIGURES Figure 1: The Station Design Toolbox GUI flowchart ................................................................................ 2 Figure 2: The user must determine the appropriate ESPG code for the station location ............................. 5 Figure 3: The Station Design Toolbox GUI, populated with user inputs from an input file ....................... 7 Figure 4: Contour plots of predicted along-range and cross-range image resolution of the camera array .. 7 Figure 5: Along-range resolution surface plot of the camera array viewed in Google Earth ...................... 8 Figure A-1: Screenshot of SVN checkout application used to load OpenEarth Toolbox........................A-1 Figure A-2: Screenshot of MATLAB Favorite Command Editor. Saving OpenEarth Toolbox as a Favorite Command provides a quick way to make the toolbox available..........................................A-2 Figure A-3: Screenshot of MATLAB Command Window print-out when OpenEarth Toolbox has been added to the path.................................................................................................................................A-3 iv EXECUTIVE SUMMARY The Station Design Toolbox is a MATLAB-based application and code repository for planning data collection from cameras mounted on a fixed platform or a small unmanned aircraft system (sUAS) in coastal or riverine environments. The following report details user instructions including descriptions of system requirements and software dependencies, tool functionality, input requirements, and toolgenerated products. E1 STATION DESIGN TOOLBOX GUI USER GUIDE 1. PURPOSE The purpose of this user guide is to describe the Station Design Toolbox GUI application. This application provides a MATLAB-based tool for users who wish to design their own camera-based monitoring station. The user can input and adjust system configuration options and visualize how changes to the configuration alter the field-of-view of the system. 2. SOFTWARE REQUIREMENTS AND DEPENDENCIES The Station Design Toolbox GUI application is a MATLAB-based application created using MATLAB App Designer. Version 2018a or later of MATLAB is required for full functionality of the Toolbox. It may be possible to run the app on older versions of MATLAB, but in order to ensure accurate operation, please update your system. The Station Design Toolbox is made available and managed by the Coastal Imaging Research Network (CIRN) GitHub repository. Git version control is used to track continuing development of this tool. The application utilizes open source code found in the Support Routines Toolbox provided by the Coastal Imaging Research Network (CIRN) and OpenEarth developed by Deltares. These open source resources are free to download and can be found at the following links: CIRN Github, Support Routines: https://github.com/Coastal-Imaging-ResearchNetwork/Support-Routines OpenEarth Wiki: https://publicwiki.deltares.nl/display/OET/OpenEarth For additional information on how to install the OpenEarth Toolbox in MATLAB, please see the appendix at the end of this document. **Note: There is a bug in OpenEarthToolbox, that at the time of app development (July 2018), had to be manually modified: Upon cloning OpenEarth Toolbox, go to the directory \matlab\applications\googleplot and open the file KMLcontour.m. In lines 156-165, replace any instances of “OPT.level” with “OPT.levels”. Additionally, the application generates geographic files that can be opened in the freely available Google Earth Pro desktop application, found here: Google Earth Pro: https://www.google.com/earth/desktop/ MATLAB App Designer was used to build the Toolbox in order to make a simple and visually clear interface for users new to camera-based observation techniques. App Designer uses a series of “callback functions” that call on routines in the CIRN GitHub repository, OpenEarth Toolbox, and functions provided within the Station Design Toolbox (found in Station-DesignToolbox\StationDesignGui\GUIroutines). In order to view the code that provides the structure of the GUI, use the “Open” button on the “Home” tab of the MATLAB toolbar and select StationDesignGui.mlapp. This opens the GUI in the App Designer interface, where “Code View” can be used to view and modify the foundational code of the GUI. Help with App Designer can be found at https://www.mathworks.com/products/matlab/app-designer.html. 1 2 3. Koetje & Palmsten USING THE STATION DESIGN TOOLBOX GUI First, clone the toolbox from https://github.com/Coastal-Imaging-Research-Network/Station-DesignToolbox using git to ensure that you are using the most recent version. The user can open the application by (1) double clicking the file StationDesignGui.mlapp or (2) navigating to the Station Design Gui directory in MATLAB and typing “StationDesignGui” in the command prompt. A window showing the application interface will appear on the screen, which includes three sections of input variables and a figure axis. To generate the output files, the user must first run OpenEarth Toolbox. Please see Appendix A for instructions on how to make a shortcut in MATLAB to run OpenEarth Toolbox. OpenEarth Toolbox must be run each time MATLAB is restarted. Figure 1: The Station Design Toolbox GUI user interface The user must provide several input arguments, indicated by empty entry fields in the GUI window (Figure 1). The user has several options for how to select these input arguments: Choose from a dropdown menu of available cameras, and enter the remaining fields manually Choose “New Camera” from the dropdown menu and enter all input variables manually Use an input file, which will auto-populate all input fields Once all input arguments are provided, the user can utilize the buttons in the bottom left corner of the GUI window. These buttons and their functions are: Save User Input Values – Clicking this button will save all user-entered input values to a .mat file that the user is prompted to name. This file can now be selected as an input file when the “Do you want to use an input file” box is checked. Plot Camera Footprint – Clicking this button will populate the figure axis in the GUI window with a polygon representing the boundaries of the camera field-of-view (referred to as footprint) for each camera in the array. The user may modify input arguments and click “Plot Camera Footprint” again to view an updated rendering of the camera footprint. Station Design Toolbox GUI User Guide 3 Generate KML Files – Once the user is satisfied with the input arguments and camera footprint, they can click the “Generate KML Files” button to create several figures and .kml. KML files can be opened in an earth browser like Google Earth. Descriptions of these output files can be found in Section 7. The buttons may be clicked in any order. In the event that the user makes a change to the camera configuration and then clicks the button to plot KML files, the camera footprint will also be updated. 4. INPUT ARGUMENTS User defined input arguments for the GUI interface are defined as follows: 1. Camera Options a) Camera Name – a string containing the name of the camera, only used for identification purposes. The user may select a camera from the dropdown menu, which will automatically pull camera chip data from Station-DesignToolbox\StationDesignGui\Inputs\cameraList.m. In the event that “New Camera” is selected from the dropdown menu, a new window appears that prompts the user to enter the following additional information: i) Camera Name – a string containing the name of the camera, as entered by the user. ii) Width of Chip in Pixels (NU) – The width of the chip or sensor, in pixels (commonly listed by the manufacturer in the form width x height, e.g. 1920x1080). iii) Height of Chip in Pixels (NV) -- The height of the chip or sensor, in pixels. iv) Width of Chip in Pixels (ssU) – The width of the chip or sensor, in mm. Some manufacturers will list a chip size in mm, but it is best to compute the size of the chip based on the size of the chip in pixels and the pixel pitch (size of a single pixel), typically reported in µm. The height of the chip (ssV), is computed by multiplying the width of the chip in mm (ssU) by the ratio of the chip height and width in pixels (NV / NU). Sometimes the chip size reported will represent the diagonal length of the chip. In this case, the width and height of the chip will need to be computed using geometry. Examples are shown in Station-DesignToolbox\StationDesignGui\Inputs\cameraList.m . b) Number of Cameras – The number of cameras in the array, up to five. It should be noted that if greater than one camera is used, the camera name, chip dimensions, focal length, elevation, and location are all assumed to be the same. The only property that varies between cameras is the individual camera azimuth, which is computed based on the camera heading (see (f) below) and accounts for overlap between camera fields-of-view defined by the user (see (g) below). c) Lens Focal Length – The focal length of the lens, in mm (e.g., 9 mm). d) Camera Tilt – the angle of the camera (or pitch) in degrees, where 0° tilt is facing straight down at the ground, and 90° tilt is facing the horizon and parallel to the ground. e) Camera Heading – the angle in degrees, with 0° oriented North, of the center of the total field-of-view for the camera array. If the array is made up of only a single camera, the heading is equal to the camera azimuth. If multiple cameras are used, the heading is the center of the sum field-of-view, accounting for overlap between camera fields of view defined by the user (see (g) below). f) Camera Elevation – the elevation of the camera, in meters, relative to the projection elevation. The projection elevation is assumed to be 0 m, so the camera elevation is the 4 Koetje & Palmsten distance from the surface of interest to the mount, tower, drone height, etc. where the camera will be located. g) Camera Overlap – the overlap in horizontal field-of-view between cameras in the array, in degrees, with a default of 5°. Overlap ensures that there are no gaps in the total fieldof-view. 2. Site Location a) Latitude – The latitude of the position of the camera, in decimal degrees, with the northern hemisphere represented by positive values and the southern hemisphere represented by negative values. b) Longitude – The longitude of the position of the camera, in decimal degrees, with locations east of the prime meridian represented by positive values and locations west of the prime meridian represented by negative values. c) EPSG Code – A numeric code (typically 4 or 5 digits) representing a geodetic parameter, or spatial reference system. See Section 6 for further guidance on how to determine the appropriate EPSG code. 3. Paths a) Path to CIRN Support Routines – the path in your local directory structure where the CIRN Support Routines toolbox has been cloned/saved. See Section 2 for a link to download the repository. The path can be manually typed-in as a string, or the button to right of the entry field ( ) can be clicked, which will open a file browser window. b) Path to Save Output Files – The path where all generated figures will be saved. The path can be manually typed-in as a string, or the button to right of the entry field ( ) can be clicked, which will open a file browser window. 5. INPUT FILES There are three files contained within the Inputs folder (Station-DesignToolbox\StationDesignGui\Inputs), all of which can be modified by the user. These files are: 1) cameraList.m – This file contains a list of cameras and their chip resolution (NU, NV) and size (ssU, ssV). See Section 4.1 for an explanation of these. Additional information is included in the comments of cameraList.m. In order to modify this file, the user should update the camera flag number (cflag) to an unused value and enter a string for the camera name (cname), chip resolution (NU, NV), and chip size (ssU, ssV). After the updating and saving the file, the camera name input by the user will now be available in the list of camera names on the drop-down menu on the GUI window. 2) inputFile_1.m – This file contains all the input arguments described in section 4. When the check box at the top of the GUI window is selected, a file browser window opens so that the user may select the desired input file. The file is then loaded and the input arguments defined in the input file auto-populate the fields in the GUI window. The provided file, inputFile_1.m, is simply an example. The user can copy and modify the file as needed to reflect the desired station parameters. The user may create multiple input files and name them as desired, so long as all input arguments are included. 3) userInputs_1.mat – This file contains the input parameters entered into the fields of the GUI window from any combination of input files or manual user entry. Input arguments are saved as a .mat file and the file can be named as desired. This is useful for tracking changes to the station design. Station Design Toolbox GUI User Guide 6. 5 DETERMINING EPSG CODE The International Association of Oil & Gas Producers (IOGP) manages a database of spatial coordinate reference systems and coordinate transformations called the European Petroleum Survey Group (EPSG) Geodetic Parameter Dataset. For the purposes of this app, use of the EPSG Dataset makes it possible to compute the camera footprint and transform the projection surface from a 2-dimensional Cartesian coordinate system (UTM) into latitude and longitude geographic coordinates [1]. The user is prompted to provide the appropriate EPSG code for the deployment location, which can be identified by finding the UTM zone of the deployment site. The UTM zone can be found through a web search or through websites like this one: https://mangomap.com/robertyoung/maps/69585/what-utm-zone-am-i-in#. Then, the EPSG code can be found through a web search (e.g. “ESPG code UTM zone 16N”) or by entering the determined UTM zone into the search bar at the following website: http://www.spatialreference.org/. The code to be entered into the GUI field is the (typically) four or five digit number listed after “ESPG:” in the search results. Coordinate systems that are based on the Word Geodetic System 1984 (WGS 84) datum are recommended, as they are regularly maintained by the U.S. National Geospatial-Intelligence Agency. For example, for the appropriate UTM zone was determined to be zone 16N for a chosen deployment station. Searching for that zone on SpatialReference.org yielded the results in Figure 2. The coordinate reference system that was selected is shown outlined in red. It was chosen because the coordinate system is based on the WGS 84 datum. The accompanying ESPG code, 32616, was entered into the field (or input file) in the GUI. Figure 2: The user must determine the appropriate ESPG code for the station location 7. OUTPUT FILES AND RESULTS When the “Generate KML Files” button is clicked, the GUI will use the provided input arguments to create 14 files that will be saved in the “Outputs” folder (Station-DesignToolbox\StationDesignGui\Outputs). Examples of these files can be found in the Example Output folder (Station-Design-Toolbox\StationDesignGui\ExampleOutput). Descriptions of these files are provided below: 6 Koetje & Palmsten Footprint.png – This figure shows a polygon representing the boundaries of the camera field-of-view (referred to as footprint) for each camera in the array, similar to that shown in the figure axis on the GUI window (Figure 3). The camera is used as the origin of the coordinate system and is represented by an asterisk. AlongRangeRes.png – This figure shows the spatial resolution of the camera field-ofview in the along-range direction, or in the direction of the camera heading (or overall array heading if more than one camera makes up the array). CrossRangeRes.png – This figure shows the spatial resolution of the camera field-ofview in the cross-range direction, or perpendicular to the direction of the camera heading (or overall array heading if more than one camera makes up the array). Resolution_AlongCrossRange_Subplot.png – This file contains a high-resolution subplot of the along-range and cross-range resolution contours, constrained to the same colorbar axis (Figure 4). AlongRangeSurf.kml and CrossRangeSurf.kml – These files contains the along-range and cross-range resolution plots, identical to AlongRangeRes.png and CrossRangeRes.png, that contain the geographic location of the camera footprint vertices. When opened in Google Earth, this file will show a resolution map overlay at the station location, providing a geospatial visualization of the estimated camera array field-of-view (Figure 5). AlongRangeSurf_ver_lft.png and CrossRangeSurf_ver_lft.png – These files contain an image file of the colorbar that appears in Google Earth when AlongRangeSurf.kml or CrossRangeSurf.kml are opened. These colorbars can be difficult to read in Google Earth, so an image file copy is provided. FootprintCamera1.kml – This file contains a shaded polygon representing the footprint of the first camera in the array and will plot as an overlay when opened in Google Earth. If more than one camera is used in the array, a footprint file will be created for each camera. **Note: If the field-of-view of the camera exceeds the horizon, the image can wrap to a nonphysical location in a manner similar to the issue of phase wrapping in signal processing. In order to prevent image wrapping, the far vertices of the camera footprint are limited to the horizon (an angle of 90° or less) if the camera tilt results in a vertical field-of-view that exceeds the horizon. Station Design Toolbox GUI User Guide Figure 3: The Station Design Toolbox GUI, populated with user inputs from an input file Figure 4: Contour plots of predicted along-range and cross-range image resolution of the camera array 7 8 Koetje & Palmsten Figure 5: Along-range resolution surface plot of the camera array viewed in Google Earth 8. LIMITATIONS The goal of this application is to allow users to quickly and easily compare camera models, lenses, camera configurations, and station locations, in order to help them make design choices at the early stages of the station design process. The camera viewing footprint and resolution predicted by the application should be taken as an estimate, not an exact representation. This application should be used to provide guidance when choosing between camera lenses, for example, or quickly testing to see if a system you are designing will capture the desired field-of-view. REFERENCES [1] EPSG, OGP. "EPSG Geodetic Parameter Dataset. International Association of Oil & Gas Producers, Geomatics Committee." (2010). Station Design Toolbox GUI User Guide A-1 APPENDIX A: INSTALLING OPENEARTH TOOLBOX How to install OpenEarth Toolbox (for Windows): 1. Install TortoiseSVN at https://tortoisesvn.net/downloads.html 2. Open file explorer to location where you want to save OpenEarth Toolbox files 3. Right click > SVN Checkout 4. Input URL of repository you want to install a. For toolbox, input https://svn.oss.deltares.nl/repos/openearthtools/trunk/ 5. Window should autofill with path to directory where you will be saving the toolbox 6. Click “OK” a. Files will begin loading – may take several hours complete this task Figure A-1: Screenshot of SVN checkout application used to load OpenEarth Toolbox 7. 8. 9. 10. 11. Once download is complete, open MATLAB Go to home tab on top toolbar Click “new favorite” at bottom. For MATLAB R2017b click “new shortcut” Enter “OET” for label (or your desired name for the toolbox on your local machine) Enter “run( path to oetsettings.m )” a. File “oetsettings.m” should be found inside the “matlab” subfolder at OpenEarthToolbox\matlab\outsettings.m. Use File Explorer to determine the path to this file on your local machine. 12. Check boxes for “Add to quick access toolbar” and “Show label on quick access toolbar” 13. Click “Save” A-2 Koetje & Palmsten Figure A-2: Screenshot of MATLAB Favorite Command Editor. Saving OpenEarth Toolbox as a Favorite Command provides a quick way to make the toolbox available. 14. To add OpenEarth Toolbox to your path, go to the home tab on the top toolbar, click the favorites dropdown menu, click OET listed under Favorite Commands. For MATLAB R2017b, click “shortcuts” tab and click OET listed under General. 15. In command window, a loading message will print as shown in Figure A-3. Figure A-3: Screenshot of MATLAB Command Window print-out when OpenEarth Toolbox has been added to the path. Station Design Toolbox GUI User Guide Resources: Setting up OpenEarth: https://publicwiki.deltares.nl/display/OET/Join+OpenEarth Checkout using TortoiseSVN: https://publicwiki.deltares.nl/display/OET/TortoiseSVN Saving OET command to MATLAB: https://publicwiki.deltares.nl/display/OET/oetsettings A-3
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : No Page Count : 16 Language : en-US Tagged PDF : Yes Create Date : 2019:03:22 16:24:02-05:00 Modify Date : 2019:03:22 16:24:02-05:00EXIF Metadata provided by EXIF.tools