The Dragonfly Java Application is a very powerful positioning and navigation system that can be customized in different ways. This page details all options and settings this system can offer and how to use it properly to compute the location of your devices.

WARNING: before going further, please make sure that all the requirements stated in the previous support pages (Requirements and Setup) are met.

1 – Getting started

Here is a quick guide about how to get started with the Dragonfly Java Application. For a deeper knowledge about ALL the configuration options, please refer to the documentation available inside the Dragonfly Web UI under the Documentation tab.

1.1 – Launch

Do you have already a set of credentials? If not already done please generate a set of Accuware credentials (usernamepassword and Site ID) filling the form at this link.

The Dragonfly Java Application can be launched in different ways (whether you need the Dragonfly Web UI or not):

  • with the Dragonfly Web UI (that will be opened inside a new Firefox window):
    • OPTION 1 – run the application by clicking the Dragonfly icon that can be found within the Ubuntu Desktop Launcher menu (as shown in the image below). Enter the credentials (username, password and Site ID) received with the Accuware Activation email. Once the credentials will be accepted by the Dragonfly Cloud server, the Dragonfly Java App will be launched and the Main tab will be available inside the Dragonfly Web UI.
    • OPTION 2 – open your browser and type the URL http://localhost:5000/. This can’t be done at first start and it can be done ONLY if the Dragonfly engine is already running.
  • without Dragonfly Web UI: go the directory where the start.sh script is located (cd dragonfly_linux/application/Dragonfly2Java_jar) and enter the following command:

About the internet connection: at first launch the credentials are immediately validated against the Accuware Dragonfly Cloud server (an Internet connection is required). Validated credentials allow you to use the Dragonfly Java App for a certain amount of time (30 days) without the need for an Internet connection.

Troubles during the login? Please get in touch with us filling this form and attach the dragonfly2.log file available under the folder cd dragonfly_linux/application/Dragonfly2Java_jar/logs

Dragonfly launcher, coming with an installation on Ubuntu 16.04
Dragonfly launcher, coming with an installation on Ubuntu 16.04

1.2 – Configuration

A bit of configuration is required before starting to navigate. Please go to the Configuration tab to do so. The Configuration tab displays several variables. Most of them are not useful for the majority of users and DO NOT need to be touched.

The parameters that need to be changed before navigating are the following:

  • CAM_MODE – monocular or stereo, depending on what type of camera is used.
  • CAM_SOURCE – this is an important configuration parameter and has 2 variances:
    • if the camera to consider is a USB camera directly connected to the Dragonfly machine you need to indicate the index of the camera to be used. The default value is -1, which advice the app to use the default system camera. If you have multiple cameras connected to your machine in order to identify the camera index, press the List cameras button on the right area of the page. This will list all the cameras available, and provide the associated indexes. If 2 monocular cameras are used for stereoscopy, enter the 2 indexes separated by a coma, beginning with the index of the left camera.
    • if the camera is a network camera you need to indicate the GStreamer pipeline or parameter string to be used by FFMPEG. Some ready to be used examples for GStreamer pipeline configurations and FFMPEG parameters are given inside this page.
  • CAM_CALIBRATION_FILE – this field should be filled with the full name of the JSON calibration file (WITHOUT the path but WITH the extension .json) that must be placed inside the config folder (cd dragonfly_linux/application/Dragonfly2Java_jar/config). How to generate the JSON calibration file? There are several possibilities:
    • USB camera directly connected to the computing unit:
      • CASE 1 – if you have purchased the Accuware Dragonfly Demonstration kit (described below) the calibration of the camera has been performed already by the Accuware support team, and the JSON calibration file is already available inside the config folder of the Dragonfly Java Application on board of the mini-PC (cd dragonfly_linux/application/Dragonfly2Java_jar/config).
      • CASE 2 – if you are using a monocular camera connected via USB to the Dragonfly machine (included the ELP-USBFHD01M-L180) then you must generate the JSON calibration file using the Accuware Camera Calibration tool available at this link and place the JSON calibration file generated by the tool inside the config folder of the Dragonfly Java Application (cd dragonfly_linux/application/Dragonfly2Java_jar/config).
      • CASE 3 – if you are using the ASTAR stereoscopic camera, connected via USB to the Dragonfly machine then:
        1. send us via email a picture of the SERIAL NUMBER written on the ASTAR stero cam.
        2. we will send you back the JSON calibration file that you have to place inside the config folder of the Dragonfly Java Application on (cd dragonfly_linux/application/Dragonfly2Java_jar/config).
      • CASE 4 – if you are using your own stereoscopic camera please contact us and let us know the exact model purchased.
    • Network cameras that makes available its H.264 or MJPEG stream to the computing unit using a network:

You could probably be interested also in the following parameters:

  • CAM_FOVwhen using:
    • the ELP MONOCULAR 180 degree camera please set this field to 120 degrees.
    • the ASTAR STEREO camera please set this field to 70 degrees.
  • POSITION_UPLOAD_INTERVAL – if the value of this field is superior to 1000 ms, the device sends its position to the Accuware server. The value defines the period at which the position is refreshed on the dashboard. An Internet connection is required. The real-time device location can be:
  • POSITION_UPLOAD_STORE – this enables to store the position in the Accuware servers, thus allowing you to get access to the device location history. An Internet connection is required. The historical device locations can be:
  • POSITION_LOG_ENABLED  this enables to store the position history of the device locally in a CSV file. This file is located under the logs folder (cd dragonfly_linux/application/Dragonfly2Java_jar/logs), is named positionlog.cvs, contains every positions the system has computed and it has an automatic daily rollover mechanism built in. All the information about the CSV files can be found at this link.
  • VIDEO_RECORDING_ENABLED – this records a video of what the camera sees during the navigation. It can be used for monitoring or for debugging purposes. Please note that the video is recorded at the speed of the location system and not at a fixed standard frame rate, so if the system was running at about 14 FPS, the frame rate of the video is 14 FPS.

Once the parameters are set, press the Save Config and Restart button. The application should take between 3 and 5 seconds to restart and apply the changes.

Configuration tab

2 – Test the positioning

Preview of the Main tab while navigating

The Positioning consists of the two sub processes: Mapping and Localization (sometimes also called Navigation). i.e. exactly what the term SLAM means – simultaneous localization and mapping. When the settings are properly configured, the positioning can be started:

  1. Go to the Main tab, and press the Start Positioning button. A preview of the camera should be displayed.
  2. At start, the system state is MAP INIT. A slow translation motion (to the left or to the right) of the camera is required in order to initialize the system (please perform a translation and NOT a pure rotation!). The warm up does not take more than 3 seconds. We recommend to perform the initialization in a scene in which there are as many small objects as possible.
  3. Once done the system state will change to NAVIGATION. At this point:
    1. inside the camera preview blue marks attached to recognized features are shown inside the camera preview.
    2. inside the plot the real-time location of your camera is shown as a moving drone! The flying drone is also reflecting the attitude of your device (pitch, roll and yaw).
  4. The drone may already have a RED thread behind it (this is your track).
  5. The drone has a light on its top. The color of the drone’s light changes depending on the status of the positioning mode:
    • GREEN – the Dragonfly engine can compute your location.
    • BLUE – the Dragonfly engine can NOT compute your location. In this situation, the Dragonfly Java App also express a corresponding audible LOST message and at the same time, all previously displayed blue feature marks should disappear. You can only correct this situation by slowly moving back to the position where you were last in the “NAVIGATION” state.
  6. Use your mouse to zoom and rotate the plot if needed or to change the perspective on the scene.

NOTES:

  • Stereo mode: in stereo mode there is no such thing as map initialization and pure rotation limitation. You can navigate without being limited in the way you moves. However, in stereo mode, the algorithm also runs slower than in monocular mode. It is thus advised to avoid moving too fast in stereo mode.
  • un-dimensional values vs WGS 84 coordinates vs metric coordinates: by default the Dragonfly Java App shows the location as un-dimensional values. To be able to see the locations provided by the Dragonfly engine as WGS 84 coordinates (latitude and longitude) and altitude or as metric coordinates (relative distances in meters to a specific origin [0,0]) you need to calibrate the map as explained inside the next section.

Info area

Below the camera preview are displayed some information:

  • Number of frame per seconds, providing indication about the speed at which the system runs.
  • Number of detected visual or virtual markersAdditional information here.
  • Number of 3D map points, which provides an indication about the size of the map. The 3D map points (a.k.a. 3D points cloud) can be visualized using the button available inside the plot when the Dragonfly Java App is used in Direct view mode.
  • The current map loaded, which is set to undefined until the map is saved.
  • The position shown as:
    • un-dimensional values (vertical, lateral, horizontal).
    • or as WGS 84 coordinates (latitude, longitude) + altitude and level ID if the map has been calibrated (as explained inside the next section) and metric coordinates (relative distances in meters to a specific origin [0,0]).
  • The attitude as pitch, yaw and roll. Additional information here.

FREQUENTLY ASKED QUESTIONS: most of the answers you are looking for can be found inside this page.

AREN’T YOU SATISFIED WITH THE RESULTS? please contact us, describe your problem and send us:

  • the exact model of the camera used.
  • the JSON calibration file of your camera. You can find it under the folder dragonfly_linux/application/Dragonfly2Java_jar/config
  • the Dragonfly LOG file (dragonfly2.log).You can find it under the folder dragonfly_linux/application/Dragonfly2Java_jar/logs
  • the Dragonfly PROPERTIES file (dragonfly2.properties).You can find it under the folder dragonfly_linux/application/Dragonfly2Java_jar/config
  • the video recorded by the camera during the navigation after having removed the CAM_FOV parameter and enabled the VIDEO_RECORDING_ENABLED parameter inside the Configuration tab of the Dragonfly WEB UI. You can find the video under the folder dragonfly_linux/application/Dragonfly2Java_jar/recorded  Please remember to click on Stop Navigation at the end of the navigation to save the video!
  • a recording of the screen of the Dragonfly WEB UI during the navigation. This can be done using one of the many screen recorders available online for free like Kazam on Linux.

3 – WGS 84 (latitude and longitude) and metric coordinates

To be able to see the locations provided by the Dragonfly engine as WGS 84 coordinates (latitude and longitude) and altitude or as metric coordinates (relative distances in meters to a specific origin [0,0]) you need to modify the Dragonfly Java App configuration to allow the calibration of the map. To do so:

  1. Select the Configuration tab.
  2. Select Three markers used (either printed or virtual) inside the MAP_CALIBRATION_METHOD parameter.

Once done you have to:

  • 4.1 – upload a detailed and scaled floor plan inside the Accuware dashboard. The floor plan is used as a reference system to setup the 3 visual (or virtual) markers.
  • 4.2 – perform the calibration of the map using 3 visual (or virtual) markers. The markers help in determining the relation of the internally used virtual coordinates to the coordinate system of the “real” world.

3.1 – Upload a floor plan

To upload your floor plan:

  1. Access the Accuware dashboard at this page using your credentials.
  2. Go under General > Floor Plans, and follow the instructions.
  3. Use the tools at the top of the map to better position and scale the floor plan (View, Zoom In/Zoom Out, OpacityAspect ratioRuler). DO NOT STRETCH IT, and KEEP THE PROPORTIONS. The inaccuracies of the floor plan will be directly reflected on the position computed by the system. If the floor plan is 50 cm inaccurate at a point, then the position will be 50 cm inaccurate at that point.
  4. Choose the level in which you want to upload the floor plan, and (optional) assign a name and a description to the floor plan, and click on Save.

At the end of the upload process the page will display the floor plan just uploaded in the table above the map.

An Internet connection is required the first time your floor plans are download rom the Accuware cloud server and to download the most updated version of your floor plans from the Accuware cloud server. 

3.2 – Calibration of the map

3.2.1 – Visual markers

Visual markers are QR-code like patterns which have to be printed and deployed through the area. It is required to create at least 3 markers, to print and deploy them through the venue prior to be able to see the locations as WGS 84 coordinates. Please note that to ensure good accuracy, it is advised that the markers are located at the extremities of the venue. In other words the best results are achieved when the 3 markers encompass the required area to be mapped. In addition to this there is no need for more than 3 markers.

If you can’t attach physical visual markers inside your environment (e.g. a museum): don’t worry. You can use virtual markers described in the next section.

Step 1 – Create the visual markers

  1. Inside the Accuware dashboard select Dragonfly > Marking.
  2. Use the buttons in the top-left corner to select Floor plan.
  3. Click on the floor plan to create a marker at the required location. It is mandatory to closely match the visual markers locations with the physical locations in which they will be placed. These are parameters you need to set:
    • Orientation: the orientation of the marker to the South-North axis. Use the slider’s arrow to set the orientation of your marker.
      1. If the marker lies on the floor, the orientation is the angle from the South-North direction to the direction the arrow displayed on the marker points to.
        Dragonfly - marker on floor
      2. If the marker is fixed on a wall, the orientation is the angle from the South-North direction to the direction the camera points to, if it looks orthogonal onto the marker. In this case, the arrow displayed on the marker has to point upwards.  
    • Altitude: the altitude of your marker to the floor in meters (e.g. 1.6 means 1.6 meters).
    • on Wall: this switch allows to tell if a marker is fixed on a wall (vertically fixed) or lies on the floor (horizontally fixed).
  4. Press Save to save the marker. Once saved, a green icon oriented according the settings chosen will be shown on the map.

You must create a total of 3 visual markers at different locations around your site by repeating steps 3 to 6.

Creation of a marker with the dashboard
Creation of a marker with the dashboard

Once the visual markers are created, it is required to print and deploy them in the real world exactly as they are set on the Dashboard. The real-world deployment must reflect the same position, altitude, orientation and disposition.

To print a marker:

  1. Go to Dragonfly > Markers using the side menu of the Accuware Dashboard.
  2. Click on a marker that has already been created.
  3. Click the Print button.

Once printed, place them where they belong inside the actual venue.

Note: please note that the visual markers are bound to their position and settings. Thus, if the position and/or settings of a visual marker have to be modified, it will be required to print it again.

Preview of a marker to be printed
Preview of a marker to be printed

Step 3 – Calibration using the visual markers

After the third visual marker has been placed you can proceed with the calibration of the map. The actual process to calibrate the map is the following:

  1. Start Dragonfly and Start positioning.
  2. Once the system is in the Mapping state, go with the device to the location of your venue where there is the first visual marker. The Markers value below inside the info area will increase of 1 unit.
  3. While still being in the Mapping state, go with the device to the location of your venue where there is the second visual marker.
  4. The Markers value below inside the info area will increase of 1 unit.
  5. While still being in the Mapping state, go with the device to the location of your venue where there is the third visual marker.
  6. The Markers value below inside the info area will increase of 1 unit.
  7. After the third marker has been detected the system should switch to Navigation state and be able to provide the accurate position of the device as WGS 84 coordinates (latitude, longitude) + altitude and metric coordinates (relative distances in meters to a specific origin [0,0]).

Note about the metric coordinates: by default the origin is the center of the floor plan:

  • X: positive when moving to the right. Negative when moving to the left.
  • Y: positive when moving to the top. Negative when moving to the bottom.

3.2.2 – Virtual markers

If the use of visual marker is not an option, there is another way to perform the map calibration without using any printed visual markers. The setup of virtual markers requires to manually enter the current position of the camera on a floor plan at 3 different locations. The locations provided to the Dragonfly Java App while performing this calibration steps described below (clicking on the floor plan) are called virtual markers (as opposed to the visual markers described previously).

Note: the setup of virtual markers is NOT necessary if the system is planned to be used with visual markers described in the previous section.

The actual process to define 3 virtual markers is the following:

  1. Start Dragonfly and Start positioning.
  2. Once the system is in the Mapping state, go with the device to the first remarkable location.
  3. When the location is reached, go to the Map calibration tab at the top of the positioning window, and select the level corresponding to the current level.
  4. Click on the floor plan at the position the device currently is. A pop-up asks for the altitude value. Enter the real altitude value and click Save marker.
  5. While still being in the Mapping state, go to a second different remarkable location with the device, then repeat 3 and 4.
  6. While still being in the Mapping state, go to a third different remarkable location with the device, then repeat 3 and 4.
  7. After the third location is entered, the system should switch to Navigation state and be able to provide the accurate position of the device as WGS 84 coordinates (latitude, longitude) + altitude and metric coordinates (relative distances in meters to a specific origin [0,0]).

Note about the metric coordinates: by default the origin is the center of the floor plan:

  • X: positive when moving to the right. Negative when moving to the left.
  • Y: positive when moving to the top. Negative when moving to the bottom.

Calibration with virtual markers
Calibration with virtual markers

4 – Maps management

When the 3 visual or virtual markers have been detected and the venue has been well discovered, the user may want to save the current state of exploration to avoid losing the work done. The Maps tab offers a couple of options to save the current map, load a different map, and also reset the map (which means restarting from scratch the positioning).

Save

In order to save the current map, fill the Save current map name and description, and press the Save button. If the saving has been successful, a new map will appear in the list below. This map can be loaded later, even after the Dragonfly Java Application has been closed.

Weight of the maps: the size of a map related to a 3D area of about 6000 m3 (made of about 20,000 Map Points) is about 100 MB.

Share

The map management system implements a feature allowing to store the map files in the Accuware cloud server. Doing this, a map created by one device can be shared among all the other devices running the Dragonfly Java App and registered on the same site. This avoids having to re-map the whole area with every new device that will make use of the Dragonfly Java App. In order to save a map in the cloud, just press the Synchronize button on the right. An Internet connection is required. This will:

  1. upload on the Accuware cloud server:
    • all the locally saved maps that are more recent than the ones already existing on the Accuware cloud server.
    • all the NEW maps that exist locally but do not exist on the Accuware cloud server.
  2. download from the Accuware cloud server:
    1. all the maps detected as more recent than the local ones.
    2. all the NEW maps not available locally.

Load

To load a map, just select a map in the list and press the Load button. When a map is loaded, return to the Main tab. The name of the loaded map should be displayed in the information dashboard. If the navigation is started, it will automatically be resumed in the loaded map and the algorithm will try to recover its position from it.

NOTE: be advised that if a map is loaded, all the unsaved progress of the previous map will be lost.

Extend

If a map previously saved map has been reused and extended, it is possible to save the progress within the same map file by pressing the Update button.

Delete

If the user is willing to discard a saved map, it is possible to delete it by pressing the Delete button.

NOTE: be advised that when pressing this button, all the unsaved progress of the previous map will be lost.

Reset

If, for some reason, a map has been wrongly generated and the navigation experience is not satisfactory, it is possible to restart the algorithm from scratch without turning it off, by pressing the Reset map button. This will delete all the current progress, and restart the navigation with zero markers and zero map-points.

NOTE: be  advised that when pressing this button, all the unsaved progress of the previous map will be lost.

Just after saving the map
Just after saving the map

5 – Quit

In order to quit the Dragonfly Java Application, enter the Configuration tab and press the Terminate button. It is indeed not sufficient to close the browser, as closing the browser just turns off the UI Web application, but not the Dragonfly server.

6 – Hard reset

If, for some reasons, the Dragonfly Java Application does not work as expect, or refuses to start even after a machine reboot, it is possible to do a hard reset of the system and to restart it from scratch. To do so:

  1. Kill any running instance of Dragonfly Java App by pressing the Terminate button inside the Configuration tab.
  2. Go to the root folder of the Dragonfly installation (cd dragonfly_linux/application/Dragonfly2Java_jar)
  3. Delete the jsmetamaps and logs folders.
  4. Go open the config folder and delete ALL the .atkn files and the dragonfly2.properties file.

When the Dragonfly Java App will be restarted, it will be as like a brand new first start.

About the maps: note that the local maps are going to be deleted as well, but not the maps on the cloud. In order to keep the local maps, do not delete the maps folder.

Folders to be deleted at the root of Dragonfly installation
Folders to be deleted at the root of Dragonfly installation

Files to be deleted in the config folder
Files to be deleted in the config folder

 

<< PREVIOUS