ninjaGUI startup flow chart
The following flow chart details the startup procedure for ninjaGUI.
ninjaGUI is started by typing the ninjaGUI command. For the current version, the command can be run by itself or adding a single argument in the form of the name of a .cfg file. If no .cfg file is provided as an argument, a browse dialog will appear to request the user to provide a .cfg file. If the user does not provide a .cfg file (by canceling) or if the .cfg file provided as an argument is invalid, a hardware configuration dialog will load instead. Said dialog will prompt the user to introduce the parameters necessary to create a new .cfg file. The program will terminate if the user is unsuccessful in providing or creating a valid .cfg file.
After the .cfg file is created and/or loaded, the setEnv function is called to set the hardware specific environment. setEnv reads the contents of the .cfg file, decides if the .cfg is specifying a compatible device, and based on that sets a series of state variables and functions that will allow the ninjaGUI to communicate with the serial device, and it will also determine the appearance of the GUI (by enabling or disabling certain features compatible with each type of hardware device).
After that, a brief communication test is performed. Basically a command requesting the hardware to return its status. If the device fails to show respond, an error or warning will be displayed indicating that, but the program will continue regardless but it will be unlikely to be able to acquire a signal.
After this brief communication test, another browse dialog will load, this time requesting a probe file. Probe files specify where each optode is located on the head, as well as the channels of interest. ninjaGUI is compatible with the probe files generated with AtlasViewer/SDGUI. We also specified a related format, the .nsd file. The nSD file specification adds a couple of features not present in the SD file format (for example, frequency selection for the sources). As there is no GUI to design the nSD files, it is desirable to use regular SD files whenever possible. The following is a list of the different hardware compatible with ninjaGUI (8/24/2021) and their compatibility with probe files:
NIRS1k: Compatible with nSD files. Compatibility with SD files possible but untested. ninjaNIRS 2020 (dual optode system): nSD file required. ninjaNIRS 2021 (single optode system): SD files are preferred.
The SD2nSD function can be used to convert an SD file to an nSD. It should only be used for ninjaNIRS 2020.
If everything is working correctly at this point, then the labstreaming layer (LSL) library will be initialized. If LSL is not found, a warning indicating this will be displayed, but otherwise the program will continue as normal (but no streaming will happen).
At this point, the main GUI form will be drawn on the screen based on all the parameters specified on the files, and main program loop will start, allowing the user to start taking measurements, as long as the communication with the hardware was established successfully. If the user desires to connect to a different type of hardware, it is necessary to stop the program and restart it with a different .cfg file.