Introduction
TuiView has lots of build-in functionality as discussed in
previous posts. However,
there are bits of functionality we did not add to TuiView but instead made available
as a plugin. This was either because the use was very obscure and didn’t seem
worth cluttering up TuiView’s codebase, or other dependencies were required and
it didn’t make sense to have TuiView package dependent upon this
other package.
Plugins are a general mechanism that you can use to embed your own
functionality on top of TuiView. This posts talks about the existing plugins in the
tuiview-plugins repository before
briefly covering how to develop a plugin yourself.
Installing tuiview-plugins
The recommended way of installing tuiview-plugins is from the git repo:
pip install git+https://github.com/ubarsc/tuiview-plugins.git
Do this into an environment where you already have TuiView installed. To explore
the plugins available, run tuiviewpluginmgr on the command line. You will be
presented with a Qt based GUI that lists the plugins available with a short
description:
Clicking the “Enabled” check box against one or more plugins will show you how
to set the TUIVIEW_PLUGINS_PATH environment variable to have it load for different types of shell.
Note that this environment variable must be set before TuiView is run to get
the plugin to load.
If you want certain plugin(s) always loaded you can make them Enabled and click
“Save and Exit”. These plugin(s) will be always Enabled when you start tuiviewpluginmgr.
To ease loading of these plugins each time you run TuiView, you can run:
eval `tuiviewpluginmgr -s`
In your ~/.bashrc (for Bash) or your ~/.tcshrc (for tcsh). This will always set
the TUIVIEW_PLUGINS_PATH for the enabled plugins when you login.
Alternatively, you can copy the relevant plugin files to one of the locations
mentioned in the TuiView Wiki.
When you start TuiView with TUIVIEW_PLUGINS_PATH set, a message will be printed to the
terminal that lists the plugins that have been loaded. Normally, plugins make a change
to TuiView’s user interface but this depends on how the plugin has been written. Let’s
look at the various plugins that are part of the tuiview-plugins repository.
GPS Marker
This plugin adds a “GPS” menu to the menu bar of each TuiView window. This plugin
assumes that gpsd has been installed on your system and has been
started and that a suitable GPS receiver has been connected to your computer.
The menu has 2 options: “Start Logging” and “Stop Logging”. When you start logging
the current GPS location will be plotted on all TuiView windows:
When the GPS location is updated, then the “bullseye” cursor will move to the new
location on all windows. When you select “Stop Logging” the cursor will be hidden.
Timeseries Plot
This plugin adds a “Timeseries Plot” menu to the menu bar of each TuiView window. The menu has 3 options:
doing a timeseries on a point, a polygon and how to summarise points in a polygon.
The intention is that you load a stack of images up within one viewer. Ideally, each
file will be annotated with the LCR_Date metadata item which specifies the date
of the image in YYYYMMDD format as shown below with gdal_edit:
gdal_edit -mo LCR_Date=20250501 image.kea
If this is not set, then each image will be assumed to be one day apart, which isn’t
normally what you are after. When LCR_Date is set, then the number of Julian days
between each image is displayed. To plot a single
point through the timeseries, select “Do a timeseries analysis on a point” from the
“Timeseries Plot” menu. Then click within the rasters and a timeseries plot will be shown:
To do a summary of polyon values through a timeseries, select “Do a timeseries analysis on a
polygon”. How the values within each polygon is summarised for the plot is controlled by the
“Polygon Summary Method” menu option. Note that like other TuiView tools, left click to create a
new vertex of the polygon and right click to close.
Note that like the profile tool, only the displayed bands are shown.
Collect Shapefile
This plugin adds a “Collect” menu to the menu bar. This plugin needs an image loaded
before it will work. The first 3 options on the menu
(“Create a new Polygon Shapefile”,”Create a new Line Shapefile” and “Create a new Point Shapefile”)
all prompt you for the name of the output shapefile to create. Once you have completed
one of these options, you can select “Collect Feature” from the menu. For polygon and
line files, left click creates a new vertex and right click finishes the feature. For
points you just need to click within the raster. When you have finished drawing features,
click the “Close Shapefile” option.
The shapefile that has been created will be in the same projection as the loaded
raster file. Each feature will have a unique FID.
Scalebar and North Arrow
This plugin adds a “Scale Bar” menu to the menu bar. This plugin can add a scale bar,
a north arrow, a citation and/or a logo to the display in the viewer. The intention is
that any time you save the current display, then these extra things will also be
saved to the .png making the result something that could be put into a report or
some other document where this extra information would be useful. To enable a
scale bar, select the “Show Scale Bar” menu option. To enable a north arrow,
select the “Show North Arrow” menu option. To add citation text, select “Set
citation text” and you will be prompted for the text to display. To add a logo,
select “Set logo” and you will be prompted for an image file to display as the logo.
Here is an example of a scale bar, north arrow, citation and logo all displayed
within a TuiView window:
QML Reader
For compatibility with QGIS, the QML Reader plugin allows .qml files to be
read and the colour information applied to a single band image via the
stretch window. This plugin just adds one button to the stretch window:
Note how there is an extra button (
) on the right hand side of the toolbar
to allow loading of the QML file. When you press this button, you will
be prompted for the QML file to apply. Once you have done this the .qml
file will be applied to the the loaded image and the stretch window will
be closed. Note that the image must be single band and that the Stretch
type will automatically be set to None before the QML is applied to match
QGIS. Note also that altering the stretch parameters and applying the
change will lose the colouring information in the window - you have to set the
colours via the QML button.
Location Broadcast
This plugin does not make any change to the user interface. It logs to a
file each time that the TuiView windows are zoomed or panned. This file
is saved under the /tmp directory, or whatever your TMP environment
variable is set to. The filename will be locationbcast_XXXX where XXXX
is your user ID (or username under Windows). Each time TuiView moves
or pans, this file is rewritten with a timestamp and the new bounds.
This idea is that other software can monitor this file and update as
needed when the location moves.
Recode
This plugin creates a “Recode” menu on the menu bar. This plugin is for
manually editing rasters by drawing polygons. Instead of updating the raster directly, it
saves each polygon and recode rules for later editing or creation of new
image with these edits applied.
To recode an image, load a thematic image into TuiView. Click “Start Recoding
Top Layer” under the “Recode” menu. To recode values in an area, click
“Recode Polygon” and select a polygon in the usual TuiView way (left click
for new vertex, right click closes). Then you will be presented with a table
of recodes to be made:
The left column shows the value in the image, the right column (which can be
edited by double clcking) shows the value you wish to change it to. Many recodes
can happen in one polygon in this way. There is space for a comment that applies
to this polygon below the table. When you click OK then the recode will be applied
to the current image so you can see the new values. However the original raster
will not be updated. You can visually see the outlines of your recode polygons
by clicking “Show Oulines of Polygons”. To change the recode rules for a polygon,
select “Edit Recodes of a Polygon” in the “Recode” menu. You can then click a
point within a polygon and the recode table will again be shown and you can make
changes as appropriate. When you want the updates saved, click “Save recodes to file”
in the “Recode” menu. This will save a JSON file with all the polygons and recodes
the same as the raster file but with .recode appended onto the file name. So, for
example, if you were editing /tmp/a.kea then your edits will be saved as /tmp/a.kea.recode.
If you were to start a new TuiView and start recoding the same image again you will
be asked whether you want to load the existing recodes and add to them, or start a
new set of recodes.
To create a new raster file from the original raster file and edits stored in a .recode
file, use the newfile_from_recode entry point that was created when you
installed tuiview-plugins.
Creating your own plugins
It is relatively easy to create your own plugins. As described in the
plugin wiki page, you need
to create a Python file with four functions plus an event handler if
your plugin needs to respond to events. Because TuiView looks at all Python
files in the directory(s) set in TUIVIEW_PLUGINS_PATH, we recommend starting
by creating a directory with just your plugin file in it:
mkdir test
export TUIVIEW_PLUGINS_PATH=`pwd`/test
# edit test/plugin.py
Below is a very simple plugin that adds a menu to the menu bar and
displays a message box when the user selects “My plugin Action”:
The source code is shown below:
from PySide6.QtCore import QObject
from PySide6.QtGui import QAction
from PySide6.QtWidgets import QMessageBox
from tuiview import pluginmanager
def name():
return 'Test'
def author():
return 'Sam Gillingham'
def description():
return 'Tests that plugin works'
class MyEventHandler(QObject):
def __init__(self, viewer):
QObject.__init__(self)
self.viewer = viewer
# this function gets called when action triggered
def myEvent(self):
QMessageBox.information(self.viewer, "Viewer", "My Plugin")
def action(actioncode, viewer):
# check for the code we are interested in
if actioncode == pluginmanager.PLUGIN_ACTION_NEWVIEWER:
# create a handler class
handler = MyEventHandler(viewer)
# create an action class
myaction = QAction(viewer, triggered=handler.myEvent)
myaction.setText("My plugin Action")
# create a new menu and install the action
mymenu = viewer.menuBar().addMenu("&My Menu")
mymenu.addAction(myaction)
# make sure the object isn't garbage collected
viewer.plugins.append(handler)
Obviously, some experience with Qt is required for building plugins. You need to
create a QObject derived class to connect to signals and handle them. This class
must be added to the plugins list of the window it belongs to so it does not
get garbage collected by Python. You also need to be aware how TuiView works
behind the scenes. The existing plugins are useful for this and there is some
developer documentation available
but the TuiView source code is the best reference.
Conclusion
The existing plugins in the tuiview-plugins repo
provide some useful extensions to TuiView functionality. There is plenty of scope
for writing specific TuiView plugins to address specific functionality that may
just be required for a particular workflow or company.
]]>
):
on the toolbar. Next to this button is a yellow button that allows you to change
the selection colour. Clicking this brings up a colour chooser and when
you select a colour, selected rows are shown as this colour on the map and the
colour of this button on the toolbar is updated.
There are also buttons to remove all selected rows (
)
and select all rows (
).
)
but the file must be in update mode - more detail on update mode is
provided below.
If you right click on a floating point column, an option called “Set
number of decimal places” appears. Use this to change the number of
decimal places from the default (2).
).
Then on the map, left click the first vertex of the polygon, then the next and the next.
When you have finished, right click and the polygon will be closed. The rows
that intersect with this polygon will be highlighted on the map and selected
in the table:
).
This operates similiarly to the Profile Tool. Left click on the start of the line, and
any vertices. Right click to end the line. Rows that intersect the line will
be highlighted on the map and selected in the table.
).
Simply click a point on the map and the row for that point will be selected.
).
A window is opened that allows you to enter an expression (plus any imports your expression may require).
Each column appears as a Python variable (actually a numpy array). There are some tricks about combining
expressions and “extra” columns provided in the help text. Entering an expression that returns a boolean
and pressing “Apply”
selects the matching rows in the table (and highlights on the map):
).
You are prompted for the name of the file to save.
This means the data from the selected rows can be imported into a spreadsheet, a database or
some other custom Python script for further processing.
).
While the file is open in update mode, this button stays down. To flush all changes to the
file, press this button again and the file will go back to being open in read only mode.
) on the toolbar.
You will be prompted for the type and name of the column