Opticks Developer Guide/Plug-In Types

Importers

When importing a data set, Opticks first displays the Open dialog which allows the user to select an importer and a file to import. It calls the getType() method on each plug-in in the plug-ins directory and, for those that return ‘Importer’, it calls their getName() and getDefaultExtensions() methods and adds the name to the ‘Importer’ selection box and the extensions to the ‘File Type’ selection box. When the user selects an importer from the selection box, Opticks calls the importer’s getDatasetParameters() method to determine if the selected file is a valid file that is recognized by the importer. If the file is valid, the Options button is enabled. If the user then presses the Options button on the Open dialog, Opticks calls the plug-in’s getDatasetParameters() method again. This allows the plug-in to parse the header of the file to be loaded and set the values in the DatasetParameters object appropriately. The Options dialog is then populated with the values in the DatasetParameters and displayed. When the user presses the Open button from the Open dialog, Opticks calls the plug-in’s getInputSpecification() and getOutputSpecification() methods. It then fills the actual values on each plug-in arg and calls the plug-in’s execute() method to import the data set.

The ImporterShell class represents the shell for an importer plug-in. Importer developers should take this class and extend it to support their importer-specific code.

const char* getDefaultExtensions()

Takes no arguments. Called by Opticks to get the valid file extensions to use as filters in the file selection dialog when importing the file. This method returns a list of the extensions supported by the importer (as set in the plug-in's constructor with the setExtensions() method). This list is returned as a character string. The string consists of description followed by one or more file extensions separated by a semicolon. Multiple file types may be specified with a double semicolon. Examples include "Landsat Header Files (*.hdr)", "TIFF Files (*.tif; *.tiff)", and "Source Files (*.c*);;Header Files (*.h)".

bool getDatasetParameters()

Takes two arguments. The first is a const char* that is the full path and filename of the dataset whose parameters are to be returned. The second argument is a pointer to a DatasetParameters object. This method fills the given DatasetParameters object with the parameters for the given file. The default implementation of this method initializes the object and sets the modifiable flag to true for all parameters. The method returns true if no errors occurred populating the DatasetParameters structure. A common error is that the given file is not in the correct format for the importer.

const void* getOptionsDialog()

This method provides an interface for which specialized options can be displayed to the user. It takes a filename, which is the current filename selected for import as an argument, and a DatasetParameters pointer as arguments. The method returns a void* pointer that is actually a handle to a Qt widget. For importers with the SensorData subtype, the QWidget is added to the existing options dialog. For other importers, the widget should be a QDialog that cen be displayed. This method should return NULL if the importer does not have its own options widget. All of the methods in Table 21 should be redefined by the importer plug-in. In interactive mode, an importer’s execute() method is called by Opticks after the user has selected a file to load and an importer to load it with. Additionally, the user may specify sampling criteria that indicate which portion of the cube is to be read. Typically, an importer plug-in will read the header of the file it is to read and use the generic importer to read the data cube. This frees the importer developer from the work of parsing the data cube according to potentially complicated sampling criteria. See Section for details on calling a plug-in from another plug-in.

Exporters

The ExporterShell class represents the shell for an exporter plug-in. Exporter developers should extend this class to support their exporter-specific code.

const char* getDefaultExtensions()

Takes no arguments. Called by Opticks to get the valid file extensions to use as filters in the file selection dialog when importing the file. This method returns a list of the extensions supported by the exporter (as set in the plug-in's constructor with the setExtensions() method). This list is returned as a character string. The string consists of description followed by one or more file extensions separated by a semicolon. Multiple file types may be specified with a double semicolon. Examples include "Landsat Header Files (*.hdr)", "TIFF Files (*.tif; *.tiff)", and "Source Files (*.c*);;Header Files (*.h)".

const void* getOptionsDialog()

This method provides an interface for which specialized options can be displayed to the user. It takes a filename, which is the current filename selected for import as an argument, and a DatasetParameters pointer as arguments. The method returns a void* pointer that is actually a handle to a Qt widget. For importers with the SensorData subtype, the QWidget is added to the existing options dialog. For other importers, the widget should be a QDialog that cen be displayed. This method should return NULL if the importer does not have its own options widget.

Viewers

The ViewerShell is used to implement modeless dialog-based plug-ins. When a plug-in extends the ViewerShell , the plug-in automatically inherits code that properly destroy a modeless dialog. To provide default functionality to destroy the modeless dialog, the ViewerShell defines the following method that must be implemented in the developer's plug-in:

virtual QWidget* getWidget() const = 0;

The ViewerShell destroys the dialog by overriding the PlugIn2::abort() method, getting the widget with getWidget(), and registering a PlugInCallback with DesktopServices to indicate that the plug-in has completed its implementation. When the callback is executed, the dialog or widget is hidden and destroyed. Then the plug-in is unloaded. Because the dialog is destroyed be calling abort(), derived plug-ins must also call the abort() method when the user closes the dialog or widget so that it will be destroyed. This typically occurs in an overridden QWidget::closeEvent() method in the modeless dialog or widget. See Section 5.3 for more details and example code for using modeless dialogs.