Cubert Utilities

Core Manual

2.8.2
Contents

1 Documentation overview 2

2 General Concept 3

3 Set Up 3
3.1 Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1.2 Factory Calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.3 Local settings (expert users) . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.4 Data connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2 Installation of Touch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.3 Installation of SDK and Documentation . . . . . . . . . . . . . . . . . . . . . . 8
3.4 Installation of PerClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.5 Configuration of Ambient light sensor . . . . . . . . . . . . . . . . . . . . . . . 8
3.6 Configuration of GPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.7 Custom Script (expert users) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.8 Path Placeholders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4 General Advice For Good Hyperspectral Data Quality 11

4.1 Brief Introduction To Spectral Imaging . . . . . . . . . . . . . . . . . . . . . . . 11
4.1.1 Direct Light Source Measurement . . . . . . . . . . . . . . . . . . . . . 11
4.1.2 Measuring An Illuminated Object . . . . . . . . . . . . . . . . . . . . . . 11
4.1.3 Mixed Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2 The Measurement Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2.1 Illumination And Light Safety . . . . . . . . . . . . . . . . . . . . . . . . 12
4.3 Distances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3.1 Thermal stability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3.2 Dark Subtract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3.3 Reflectance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.3.4 Spectral Radiance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

5 Troubleshooting 14
5.1 Cubert Utils Touch Can’t Connect . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.2 Camera Not Getting Online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.3 Frame Loss / Incomplete images . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.4 *_cube.tiff Does Not Contain Meta-Information . . . . . . . . . . . . . . . . . . 15

6 Support 15
 1 DOCUMENTATION OVERVIEW

Software Guides
Cubert Utilities CORE manual (This document) The Core application as
well as the general overview on the opera-
tion of the different components. Also, gen-
eral accessories.
Cubert Utilities TOUCH manual The guide for the featured GUI for operat-
ing Hyperspectral Cameras and respective
data. Also, general advises on operating
the camera are given
CubertUtilsCommandList.html The documentation of all SDK commands
(html file).
Cubert Utilities User Plug-Ins manual A guide for generating self-made view plug-
ins.

Hardware Guides
ULTRIS Hardware and Operation Guide Documetation of ULTRIS (X50, X50P, X20,
X20P, S5, and legacy models).
FireflEYE Hardware and Operation Guide Documetation of FireflEYE (V185SE,
V185ST, and legacy models).

Application Notes & Tutorials

www.cubert-hyperspectral.com Please refer to the website for application
notes and tutorials.

Table 1: Documentation overview

Page 2 of 15

Cubert Utilities Core Manual (v. 2.8.2)

 3 SET UP

2 General Concept process will ensure that all dependencies are

installed.
The Cubert Utils represent a three-tier sys- After the installation process you are
tem. The first tier represents the physical hy- prompted to active the software by providing
perspectral camera with its hardware prepro- the shipped license file (fig. 3). This will start
cessing and digitalization. the activation of the camera and also con-
The second tier, the application layer, is Cu- figure the camera, if connected. You will be
bert Utils Core. This application abstracts prompted to select performance settings ac-
the hardware and provides the unified saving cording to your system configuration. Please
format and communication. ensure the camera is connected to the sys-
The thirds tier, the presentation layer, is im- tem for the automatic interface configuration
plemented by the GUI Cubert Utils Touch as to function.
well as custom SDK applications.
The connection between camera and Cu-
bert Utils Core is a proprietary protocol, which
will differ over the camera models. The con-
nection between Core and any presentation
software is a TCP/IP connection with a SOAP
protocol.

3 Set Up
The setup of a system is strongly dependent
on the camera model. Thus, we will sepa-
rate the general installation from the camera-
specific setup.

3.1 Core
3.1.1 Installation

Cubert Utils Core is required to be installed

the computer that has physical connection to
the hyperspectral camera as well as comput-
ers for offline proceesing of data.
For a flight solution, Cubert Utils Core
needs to be installed on the MiniPC. However,
depending on your purchase, this has already
been done by Cubert. The same applies for
pre-installed Laptops by Cubert.
For all other systems, start the shipped in-
staller and during the setup procedure select
to install CORE.
The installer will guide you through the
setup process. First select the directory in
which the software should be installed (fig. 1).
After that the components, which will be in-
stalled, are selected (fig. 2). The installation

Page 3 of 15

Cubert Utilities Core Manual (v. 2.8.2)

 3 SET UP

Figure 1: The Cubert Utilities Installer

Figure 2: The Components which can be selected (May differ from your version)

Figure 3: Provide the license file which was shipped with this installer

Page 4 of 15

Cubert Utilities Core Manual (v. 2.8.2)

 3 SET UP

Note:
The local settings should only be changed manually by expert users. Rather use the
default options offered by the factory file installer.

3.1.2 Factory Calibration • soap_port set the port for the network
connection between Cubert Utils Core
This step is automatically started, when in- and Cubert Utils Touch (formerly: envi-
stalling the camera’s license. If you are up- ronmental variable SOAPPORT)
grading to a newer camera calibration or from
a demo license to a commercial license you • max_raw_fps sets a maximum frame
are not required to re-run the setup of Cubert rate for Raw and Dark Subtract capture
Utilites. Instead run the FactoryFileInstaller, mode. This option allows fine tuning a
which will also install the license associated system for the actual performance con-
with the camera. straints of a system. (formerly GPIO-
The camera’s calibration files are stored RAWFPS)
in the <INSTALL DIR>/Bin/factory directory.
You must not modify these files manually, but • max_ref_fps sets a maximum frame rate
rather use the factory installer. If the directory for Reflectance capture mode. This op-
is empty, Core will fall back to offline-operation tion allows fine tuning a system for the
(demo mode). actual performance constraints of a sys-
tem.

3.1.3 Local settings (expert users) • auto_exp_max_fps sets the maximum

frame rate for processing the auto expo-
With the exception of the camera factory sure. When the actual acquisition ex-
calibration (see below) all local settings are ceeds this speed, frames for calculat-
stored in the settings directory <INSTALL ing the exposure metrics will be skipped.
DIR>/Bin/user/settings The default is 3 fps.
The .settings- files contain variable values
that can be changed depending on your sys- • no_valid_init forces to ignore validation
tem. checks of the factory calibration. For de-
Note, that there are separate files for gen- velopment device only.
eral settings and product-specific values and
view settings (see the respective product • max_sensor_desync is the maximum
manual). time (in milliseconds) that the internal
The general settings are used for tweaking sensors of the camera may become out
the performance. The values are: of sync, before trying to auto-correct. Un-
der normal circumstances, sensors must
core.settings
not get out of sync, but for week sys-
For Cubert Utils Core some options may re-
tems or high-performance, this correc-
quire tweaking. Cubert Utils Core in general
tion might be needed. Not all sensors
is controlled by the core.settings file.
support this option. Default: 100.

• measurement_dir set the default sav- • max_rel_time_diff The maximum rela-

ing directory. Per default, the documents tive time difference between a measure-
folder of the user will be used. (formerly: ment and the references it used. If ex-
CUBERTDIR) ceeded, the receptive heuristic will pro-

Page 5 of 15

Cubert Utilities Core Manual (v. 2.8.2)

 3 SET UP

duce a warning. Default value: 0.01 • view_fps set the frame-rate for process-
(1%). ing of live previews (default: 5 fps).
This does not affect the recording speed,
• abs_temperature_diff The maximum
but will severely influence your system
sensor temperature difference (in De-
performance. If you encounter perfor-
gree Celsius) between a measurement
mance issues, decrease that number.
and the references it used. If exceeded,
For the MiniPC in the flight solution, a
the receptive heuristic will produce a
value of 0.5 is recommended (formerly
warning. Default value: 5 (5 °C).
SLOWFPS).
If a GPS module is configured, addition- • view_bandwidth set a bandwidth limit
ally the following values are used (windows for live previews (in MB/s, default: 5). If
only). The default values represent the re- the limit is reached, the transmitted im-
quirements of the NMEA 0183 protocol. ages will be shrunk. The bandwidth is
• force_gps_port use this serial port for applied before transmission encoding.
GPS module, instead of searching (from • view_bandwidth_dampending The
0-19). bandwidth will change more smoothly, if
• gps_baud the baud rate. Possible val- a value below 1 is given for this property.
ues are: 110, 300, 600, 1200, 2400, Give values between 0.1 and 1.0 (default
4800, 9600, 14400, 19200, 38400, 0.3).
56000, 57600 115200, 128000 and
• view_size_gallery In gallery mode or
256000 (default: 4800).
with the command view_get a view is
• gps_databits the number of data bits also transmitted. This view will not re-
(default: 8). spect the view_bandwidth-setting. In-
stead the total size of the data package
• gps_stopbits the number of stop bits. will be limited to the size defined by this
Assign the values a follows: property (in MB, default: 100)
– ONESTOPBIT → 0 • view_size_gallery_preview In gallery
– ONE5STOPBITS → 1 mode preview or with the command
– TWOSTOPBITS → 2 (default: 0) file_get a view is also transmit-
ted. This view will not respect the
• gps_parity the parity, assign the follow- view_bandwidth-setting. Instead the
ing values: total size of the data package will be lim-
– NOPARITY → 0 ited to the size defined by this property
(in MB, default: 0.1).
– ODDPARITY → 1
– EVENPARITY → 2 • soap_io_chunk En-/Disables HTTP
chunking for SOAP transmission. Set to
– MARKPARITY → 3
true/false (default: false).
– SPACEPARITY → 4 (default: 0)
• soap_zlib En-/Disables zlib compres-
system.settings sion for transmission. Set to true/false
The system.settings contains computer- (default: false).
specific performance settings. This file is gen-
erally set (and overwritten) by the factory file • soap_worker_thd_cnt Defines the
installation, but can be changed manually. It number of worker threads for the SOAP
contains the following option: server (default: 4)

Page 6 of 15

Cubert Utilities Core Manual (v. 2.8.2)

 3 SET UP

• soap_package_queue Defines the ally set by the installation, but can be modified
number of requests buffered by the manually.
SOAP server’s dispatcher, before
• miraDevice The hardware resource
discarding new messages (default: 100).
which wll be used by the classifier (de-
• soap_imgformat Defines the image for- fault: 0 (CPU)). See log output for avail-
mat for view_get and file_get functions. able devices.
Default is jpg (with e.g. 80% compres-
• miraAllowGPU Allow the usage of GPU-
sion), possible values: jpg, tiff (default:
optimized runtime. (default: false (CPU
jpg). Note: CubertUtilsTouch will not re-
only)).
spect this propery, and expect jpg encod-
ing. Furthermore, hardware-specific settings
files are created by the factory file installer.
• soap_jpg_quality Gives the jpg qualiy Please refer to the respective hardware
value for compression (0 - 100, default: guides on details.
90) Please note that the system.settings, the
• file_compression De-/Activate com- hardware-specific .settings files and the ac-
pression of .cu3-files and (if available) tiff tual measurement system depend on each
files (LZW). If activated, measurements other. If you change one option you will likely
cannot be opened by software versions have to adjust others as well. E.g. a higher
prior 2.7.0 (default: true) frame transmission delay will lead to a longer
time to record a single image; thus, the time-
• file_fragment allow file fragmentation out settings may not be appropriate. The
(saving the image files outside the CU3). manual editing of any of these settings is rec-
(default: true) ommended for expert users, only. As default,
you should select from the performance op-
• allow_packed_transmision Allow the tions of your factory file installer. If you en-
usage of a packed (compressed) trans- counter problems, try the other available op-
mission between camera and CORE. tions before consulting to changing any of
This option should be set to "false" on these options manually.
very weak PC, e.g. "miniPC2" (default:
true) 3.1.4 Data connection
• wait_time_integration_time_factor, Cubert’s hyperspectral cameras can be oper-
wait_time_integration_time_offset, ated in different modes. In principle, the hy-
wait_time_average_count_offset perspectral camera can be operated with the
These parameters determine the waiting
following two operation schemes:
time for a single image (snapshot, Direct connection
capture). The total timeout waiting
For operation, directly connect your PC’s NIC-
time is calculated as: ttimeout =
s/USB1 to the camera via respective cable(s).
(ctime_factor · texposure + ctime_oset ) ·
Your client PC will be used as Cubert server
Naverages + caverage_count_oset . and Cubert client at the same time.
Remote controlled
• histogram_max_sz Maxiumm total size
For remote-controlled operation connect your
of histogram (default 2000000).
camera to the Cubert Mini-PC server. If your
mira.settings camera has multiple network connections, is
The mira.settings contains settings regard- 1
depending on the camera, see respective hardware
ing the perClass Mira library. This is gener- and operation guide

Page 7 of 15

Cubert Utilities Core Manual (v. 2.8.2)

 3 SET UP

crucial, that you connect the correct respec- If you encounter problems with the internet-
tive network ports. The pre-installed Cubert based activation, please contact support.
Mini-PC server will automatically establish the Please also regard the abundant docu-
connection to the camera and run the server mentation at PS SysDesign’s web page:
process upon power-up. It can be accessed http://perclass.com/cubert
by any other PC with installed client software
(recommended: Cubert Utils Touch) via WiFi.
3.5 Configuration of Ambient light
sensor
3.2 Installation of Touch
The major part of the ambient light sensor’s
The installation of Cubert Utils Touch can be (e.g. "q-Mini") configuration is included to the
selected in installation wizard. For configura- factory calibration of your camera. The re-
tion details and operation refer to the separate quired drivers are installed together with the
guide Cubert Utils Touch manual. installation of Cubert Utils Core.
When starting Cubert Utils Core, the log
3.3 Installation of SDK and Documen- window will show the load level of the ambient
tation light sensor, if it is properly connected. Also,
you can see the system status in Cubert Utils
The SDK examples and the documentation Touch, see chapter 2.7 in the respective man-
can be selected for setup in the installation ual. This chapter also explains how to set an
wizard. They will be located in the instal- integration time factor.
lation directory selected, by default this is Please connect the Qmini with the USB
C:\Program Files \CubertFuchsia\ port to the computer. After starting the Cu-
bert Utils Touch, the device will be detected
3.4 Installation of PerClass automatically. Whether the Qmini has been
detected successfully can be verified by going
PR SysDesign’s classification engine per- to the Operation Settings, Advanced Options
Class is installed automatically with the and Qmini tab in the Cubert Utils Touch. A
CORE package, the respective Toolbox for green circle indicates that the device is oper-
generating classification pipelines with Matlab ational. A red circle indicates an error mes-
can be selected for installation during setup. sage. Please check in the Core window if
For activating perClass Runtime, enter the a corresponding error message is displayed
activation key in the log window of Cubert and follow the instructions.
Utils Touch (see Cubert Utils Touch manual, Setting the integration time factor is the
chapter 7.6). This requires an internet con- most challenging part of a proper set up with
nection. the ambient light sensor. We recommend the
For activation of the toolbox, start Mat- following strategy.
lab and add perClass to the path (e.g. First, set up your hyperspectral camera’s in-
C:\Program Files\CubertFuchsia\perClass\). tegration time, as such, you ensure, that you
In Matlab run the command sdactivate. This will have as many counts as possible for your
required internet connection. actual measurement without over-illuminating
The Runtime license file will be lo- it.
cated in %ALLUSERSPROFILE% \CubertU- Next, point the ambient light sensor with co-
tilsCore\license sine corrector in place to the light source or
The Toolbox license will be located in the the sky. The viewing filed must not contain
directory where the Matlab files for the toolbox any local objects, if you intend to move the
are stored. whole system.

Page 8 of 15

Cubert Utilities Core Manual (v. 2.8.2)

 3 SET UP

Next, change the integration time factor of 3.6 Configuration of GPS

the ambient light sensor to produce a load
The GPS link is automatically established, if
level that allows enough increase to cover the
a Cubert-specified GPS is connected to the
changes of your light source, e.g. 80% (0.8)
system. As yet, the USB-to-serial converter’s
if you expect the light source to brighten by a
driver is not automatically installed. Please
maximum of 25%.
install the driver shipped with the GPS, first.
The GPS module must be activated in the
Finally, point your camera to white target,
factory file. In principle, Cubert Utils Core
record a white reference. For outdoor mea-
supports NMEA 0183 protocol v. 3.01 (via
surements, we suggest doing the white ref-
RS232 serial connection, no warranty).
erence within full sunlight to compensate for
When a GPS is connected, it will be dis-
the full saturation. When the desired situa-
played as “online” in Cubert Utils Touch (see
tion has occurred, proceed with referencing
chapter 2.7 in the respective manual). If a lock
the white target. The dark reference must be
is acquired, this is displayed in the log output.
set while both camera and ambient light sen-
To fine-tune the serial port settings for GPS,
sor are fully covered.
refer to chapter 3.1.3.
The whole procedure requires a lot of expe-
rience. We recommend testing the whole pro- 3.7 Custom Script (expert users)
cedure indoors with an artificial light source, It is possible to configure custom scripts.
first. Modify the hooks.xml file in the <INSTALL
DIR>/bin/user/hooks directory. The possible
The provided correction alogirithm is exper- commands are defined by a schema definition
imental. The recorded ambient light sensor located in:
data can be accessed via image details in <INSTALL DIR>/ bin/ xsd_schemes/
Cubert Utils Touch. Also, the recorded ambi- commands.xsd
ent spectra can be manually exported to disk The execution of a script is determined by
as separate CSV files using the export func- the hook’s id, currently the following events
tion in the gallery mode, by exporting measur- are supported:
ments as TIFF or ENVI Files.
• onStart execute the script after the cam-
Note: With the default software setup, the era becomes online.
Cubert camera data is not automatically cor-
The following example loads the dark “My-
rected with the ambient light sensor data,
Dark.cu3”, sets it as dark, then “MyWhite.cu3”
when viewing in Live-View or writing to the
and sets it as white. Finally, it switches to re-
CU3 format. This can be specified by the
flectance mode.
user. However, we recommend not to acti-
Note, that the script will simply continue
vate the automatic fusion of camera measure-
upon any error. see the picture: 4
ments and data from the ambient light sen-
sor, otherwise the original measurement can
3.8 Path Placeholders
no longer be extracted in retrospective. We
strongly recommend the use of an ambient Loading files from disk can be performed in
light correction algorithm adapted to the spe- absolute and relative paths. Relative paths
cific setup and application and implemented will be relative to the working directory from
by the customer for its own environment and where Cubert Utils Core has been started.
to fuse the hyperspectral measurements with Some special placeholders can be used to
the ambient light data in a post-processing obtain typical storage locations without exact
step. knowledge of the respective absolute path:

Page 9 of 15

Cubert Utilities Core Manual (v. 2.8.2)

 3 SET UP

Figure 4: Code example

Page 10 of 15

Cubert Utilities Core Manual (v. 2.8.2)

 4 GENERAL ADVICE FOR GOOD HYPERSPECTRAL DATA
QUALITY

Note:
This chapter does not replace training.

• {factory_file_directory} The location of The region of light "seen" by the human eye
the factory calibration of a camera. is called the visible spectrum, but there are
also wavelength regions that are beyond the
• {user_dir} The user-dir used by Cubert visible spectrum. Light originates from a light
Utils Core. source and is eventually detected. On the way
it can be reflected, refracted, scattered and/or
4 General Advice For Good Hy- absorbed by the environment.
perspectral Data Quality
4.1.1 Direct Light Source Measurement
Cutting-edge hyperspectral technology is still
When directly measuring a light source with a
bound by physical restrictions. Thus, depend-
spectrometer, the matter between light source
ing on the application, special attention needs
and detector may disturb the measurement
to be given to the measurement preparation
(for example Oxygen will absorb light and cre-
and the selection of the light source, as well
ate an absorption peak at 760 nm). Another
as the camera settings. Also, the recom-
example is measuring a plasma. The recom-
mended processing modes strongly depend
mended mode for this kind of measurement is
on the kind of measurement that you want to
Spectral Radiance (see chapter 4.3.4). Note:
perform.
do not point the hyperspectral camera di-
rectly at the sun.
4.1 Brief Introduction To Spectral
Imaging
4.1.2 Measuring An Illuminated Object
Light is what a detector sees and is composed
of spectral bands. E.g. sun light is composed When measuring an illuminated object3 , the
of light from ultra-violet to infra-red. illumination still originates from a light
The human eye has two types of photore- source. The object will attenuate, scatter
ceptors, rods and cones. The cones are and/or refract different wavelengths and this
what helps the human brain to perceive color. modified light will then be detected. This mea-
There are three types of cones: blue, green sured light yields the combined information
and red and the signal from these cones is about the light source and the measured ob-
processed by the brain to give the impression ject. If the light source does not provide an
of color. However, color is not the same as even, continuous broad spectrum, erroneous
a spectrum. For instance, a yellow color im- spectral information will be given about the
pression can be created by a monochromatic object.
yellow light source (580 nm source) but also This physical limitation can be circum-
by adding two entirely different light sources vented by setting the measurement in rela-
(580 nm "red" and 532 nm "green"). The color tion to a known object (typically a broad-band
impression will be the same, but the spectral white surface). As such, the properties of the
signal is entirely different. light source cancel out. The resulting spec-
Light is an electro-magnetic wave2 and can trum reads as "relative to calibration target" or
have different wavelengths and brightness. simply "reflectance".
2 3
No going into the rabbit-hole of QED here i.e. not a light source itself

Page 11 of 15

Cubert Utilities Core Manual (v. 2.8.2)

 4 GENERAL ADVICE FOR GOOD HYPERSPECTRAL DATA
QUALITY

Note:
Light measured from an object always originates from a light source, not the object.

There are limitations to this method, how- mended mode for this kind of measurement
ever. If a light source does not contain the is Spectral Radiance (see chapter 4.3.4).
full spectrum of light, the missing wavelengths In most cases, it is crucial to not acciden-
cannot be measured by for the object. A poor tally have a mixed setup, and unknowingly
light source choice will reduce the bands of disturbing measured spectra. This is most
the hyperspectral camera. Also, the oppo- prominent for undetected UV-fluorescence
site is true: strong spectral spikes of a light while measuring in reflectance mode.
source (e.g. atomic emission bands in fluo-
rescent lamps or xenon light sources) crate a 4.2 The Measurement Setup
very challanging measurement situation and
may lead to a loss of measured bands. See The current chapter will assume reflectance
chapter 4.2.1 for details on light source selec- measurements. However, the information ap-
tion. plies to other measurement modes.
Outdoor reflectance measurements are in-
trinsically very complex to perform. First, the 4.2.1 Illumination And Light Safety
sun’s illumination has a characteristic spec- As mentioned above, proper illumination is
trum that is modified by the atmosphere. crucial for measuring hyperspectral images.
Local changes in cloud coverage, humidity, Before even considering the camera, you
ozone level and temperature will modify the should verify that your light source is bright
effective illumination and thus generate arti- enough in the bands needed to measure
facts in the measured images. Also, even for your object. However, this might involve
clear skies the illumination is a combination light sources that are dangerous due to
of direct sunlight and indirect (ambient) light their brightness and/or components in ultra-
from the sky itself. violet/infra-red bands. Thus,
Finally, the light source might interact with
the measured object. Most prominent exam- • always follow the safety advice of
ples are UV-fluorescence resulting in a too your lamp’s supplier,
bright blue-band signal, as well changes as
the O2 absorption band introduced by photo- • do follow local guidelines and restric-
synthesis in plants. tions regarding light safety,
The recommended mode for this kind of • do not look into the sun or point the
measurement is Reflectance (see chapter camera directly at the sun,
4.3.3)
• and take appropriate protective mea-
4.1.3 Mixed Setup sures:
Protect against invisible ultra-violet
An object may interact with light and at the light!
same time emit light itself. Examples of this Protect against invisible infra-red
are fluorescence and black-body radiation. In light!
this case it is very difficult to separate the ef-
fects of the two phenomena. Deep a-priori Typically, you want to use a black-body radi-
knowledge about the light source and the ator such as a halogen light or incandescent
measured objects is required. The recom- light bulb, sunlight, or a sulfur lamp as your

Page 12 of 15

Cubert Utilities Core Manual (v. 2.8.2)

 4 GENERAL ADVICE FOR GOOD HYPERSPECTRAL DATA
QUALITY

Note:
Be very cautious about effects of fluorescence, especially when working in the UV-region
or with UV light sources

light source. The following are unsuitable light the white reference (LO = LW). For the same
sources: Fluorescent lights, lasers, mercury reason, the distance from the object to the
lamps. LED and Xenon light sources may camera (OC) and the distance from the white
work depending on the specific light source target to the camera (WC) must not change
and the object you want to measure. for non-uniform light sources.
Depending on the light source type, you In some models the distance from the cam-
need to take into account it’s power sup- era to the object (OC) must be known or cali-
ply. AC power typically yields an oscilla- brated in a separate step. Note: do not oper-
tion spectrum (50 Hz / 60 Hz). Some light ate the camera outside the specified distance
sources drivers produce noticeable fluctua- range.
tions in brightness over time. Examples are:
PWM’s of LED drivers and fluorescent light 4.3.1 Thermal stability
drivers.
Also, most light sources require stable ther-Not only does the light source need to be ther-
mal conditions and a warm-up time. E.g. a mally stable, but so does the camera. All
stabilized halogen light source with DC power power consumed by the camera will eventu-
supply and 150 W power consumption may ally dissipate as heat. Heat will change the
still take one hour to stabilize. Also note thatsensor’s optical response. Thus, we recom-
even a professional light source’s spectrum mend the following: Let the camera warm up
might still drift over time and leave parts of until its sensor’s temperature is stable. Leave
the spectral range unusable for the measure- the light source on, because the light source
ment. might warm up the camera as well. Do not
change camera mounting. The mount will in-
4.3 Distances fluence the cooling properties of the camera.
Hint: the sensor’s temperature can be read
In a reflectance setup there are multiple rele- from recorded meta-information of the image.
vant distances.

• Distance Light source to measured ob- 4.3.2 Dark Subtract

ject (LO)
With a warmed-up light source and thermally
• Distance Object to camera (OC) stable camera you are ready to begin. First,
select the exposure time (integration time)
• Distance Light source to white target you want to operate, taking into account the
(LW) proper dynamic range for both your measured
object and - if you intend to work in reflectance
• Distance White target to camera (WC)
mode - your white reference pattern. Next,
The distance from the light source to the mea- cover the camera (e.g lens cap) and record
sured object (LO) must be taken into account a "dark" setting (DARK). The dark is used
when nusing a on-uniform light source (which for removing dark noise offsets from the mea-
are practically all light sources except the sun) surement. The image IDS is calculated from
As the brightness changes over distance, the the raw measurement IRAW as follows:
object must be placed at the same distance as IDS = IREF − DARK
Page 13 of 15

Cubert Utilities Core Manual (v. 2.8.2)

 5 TROUBLESHOOTING

Note:
DARK and WHITE references should be taken at the same integration time and thermal
conditions as the measurement

For technical reasons the final result is trun- The spectral radiance image is stored as a
cated below 0 counts (no negative values al- 32-bit floating point image without any trunca-
lowed). tion (IEEE 754, single precision). The unit is
W m−2 sr−1 µm−1 .
4.3.3 Reflectance Note: Though the purpose of the Spectral
Radiance mode is to be independent of the
As with Dark Subtract, the Reflectance mode
camera properties, the dynamic range of the
requires a proper dark measurement. Per-
raw measurement will still influence the mea-
form the steps to record a dark and then mea-
surement. Thus, you should always check
sure a broad band white target. Record the
raw measurement before using the spectral
white at the same distance as you want to
radiance mode. In raw mode set the integra-
measure your object. Leave the integration
tion time to a value where the camera is not
time at the same value as with recording the
saturated, typically a value of 70% of it’s max-
dark. Do not change it for recording the ob-
imum count value is best.
ject.
For a Reflectance image IREF , the white
Also note: The spectral radiance calibration
reference WHITE is used to compensate for
is optimized for the integration time required
for outdoor NADIR measurements of vegeta-
the spectral properties of the light source. The
DARK is used for removing the dark noise tion. Operating with different integration times
offsets in both IREF and WHITE measure-
may yield abnormalities.
ments. It is calculated as follows.

IRAW − DARK
IREF = WHITE
5 Troubleshooting
− DARK
(1)
When you encounter a problem you should
For technical reasons, the result is trun-
verify that you are using the latest software
cated at values below zero and above
version and also check the release notes for
655.35%. The result is stored in a fixed-
known issues respective workarounds.
comma format. 10 000 counts correspond to
a value of 100%.
Note: If the camera is not thermally stable, 5.1 Cubert Utils Touch Can’t Connect
the DARK might not be the actual dark noise
of the WHITE and/or the raw measurement
A commonly known issue is that Cubert Utils

IRAW . This will lead to non-linear artifacts in Touch will not connect to Cubert Utils Core.
Please ensure that the network connection
the spectrum.
is reachable and Core is running.
If so, verify that the Core’s network service
4.3.4 Spectral Radiance
is running. Search for command prompt in
As with Dark Subtract, the Spectral Radiance the start menu of your operating system, right
mode requires a proper dark measurement. click and run as administrator. In the console
Due to the mechanical movements of internal box enter “netstat -b -a” and search for Cuber-
parts introduced by thermal expansion some tUtilsCore.exe
models additionally require a white reference If the application can be found in the list,
measurement used for local flat-fielding. you probably have an issue with the fire-

Page 14 of 15

Cubert Utilities Core Manual (v. 2.8.2)

 6 SUPPORT

wall. Ensure, that the firewall allows Cuber- out time of sensor" of all sensors and com-
tUtilsCore.exe to server on the port 9392. pare the time stamps. All sensors have have
If the CubertUtilsCore.exe is not in the list, internal quartz clocks that naturally drift over
you need to change the network port. Change time. Their time is monitored and slight de-
the settings variable soap_port and set a free viations between sensors are actively cor-
port number as value, e.g. 4563. Restart Cu- rected each time an images is recorded. If
bert Utils Core. your don’t record an image for a long time,
these times might have exceeded the value
5.2 Camera Not Getting Online of max_sensor_desync and thus the im-
age assignment might fail. There are two
For the camera not going online there might ways to circumvent this problem. Either in-
be several reasons. Please closely observe crease the value of max_sensor_desync, or
the log window, if it complains about faulty record an extra image right before recording
network connections. If so, fix the setting ac- your actual measurement (the extra image
cording to the hardware operation guide of the will re-sync the sensor clocks in most cases).
camera. This may quite commonly be, that Please not the the sensor synchronization is
you simply switched the network cables. primary conducted by the frame counter and
If this does not help, please contact your not the sensor’s time. The time is only needed
distributor for support (see chapter 6). for detecting possible frame losses. If you
do not encounter frame losses, the value of
5.3 Frame Loss / Incomplete images max_sensor_desync can be increased to a
very large value to disable this controlling al-
In certain setups images may drop or be gorithm entirely.
incomplete. In such cases, the CubertU-
tilsCore program should be started with the
5.4 *_cube.tiff Does Not Contain
console option "-v". This will generate a
Meta-Information
verbose log output "CubertUtilsCore.exe.log"
(windows) or "CubertUtilsCore.log" (linux). Some cameras directly store a *_cube.tiff
The log output will contain additional infor- when recording images. This Tiff-file is a valid
mation: multi-channel tiff of the hyperspectral cube
image incomplete If images are incom- (without pan-sharpening) and can directly be
plete this hints at poor performance of the used for further processing. This file, how-
network interface card (NIC) or it’s driver or ever, does not contain any meta information
the PC’s general performance. This can often such as the processing mode, the GPS-IFD
be circumvent by replacing the NIC or chang- or the channel names. For obtaining a Tiff file
ing the performance settings (specific for the with this information, use the file export func-
camera model, see respective manual). tions provided.
capture failed, time-out Timeouts during
capture can also be a performance problem.
They most prominently occur for averaged im-
6 Support
ages with long exposure time. You can tweak In general, the technical support for Cu-
the wait_time_integration_time_factor, bert hyperspectral cameras is provided by
wait_time_integration_time_offset and your local distributor; refer to: https://www.
wait_time_average_count_offset to cir- cubert-hyperspectral.com
cumvent this problem.
readout time of sensor On a multi-sensor
system, panchromatic images might be miss-
ing over time. Check for the reading "read-

Page 15 of 15

Cubert Utilities Core Manual (v. 2.8.2)