The Multifile input method

The multifile input method allows multiple monochrome files of "standard" types like PNG and BMP to be imported as multispectral images. It can also read raw binary files.

Each file is flattened to greyscale in the process (if it is RGB) by finding the mean of the three channels for each pixel.

Camera data files

In order to analyse the images, PCOT needs to be able to find out which filter was used for each image and get information about it. It also needs access to calibration information, for example flat and dark field images, and reflectance data.

This data is stored in PARC files - PCOT archives - and is generated by the pcot gencam command. If you want to know to make them yourself, read this documentation.

However, PCOT already comes with some camera files. These can be found in the cameras directory inside the PCOT directory. They do not have flat/dark fields because that data is very large, but hopefully you will not need them - that stage of processing will take place upstream in the ROC. Other camera data files can be downloaded from the PCOT Cookbook.

Finding out about camera data with lscams

You can find out about the camera data installed on your system with pcot lscams (list cameras). Alone, this will list the cameras with their short descriptions.

You can get a list of the filters for a camera by using the command pcot lscams -f. Alone, this will list all cameras and their filters, but you can specify a camera: pcot lscams -f TRAINING_GEOLOGY will list all filters for the geology filter wheel on the training model, for example (if you have that camera data file installed).

Each filter has a name and a position, as well as other data like centre wavelength, FWHM and so on. Filters may also have reflectance and flat/darkfield data - you can see if this is the case from the pcot lscams -l command: if a camera has flats, you'll see "Has flats" in the description; if it has reflectance data, you'll see a list of supported reflectance calibration targets.

Setting a camera

Once you know what camera was used, and you have installed a data file for that camera, you can set it in the multifile input using the Camera widget.

Which image is which filter? Setting a file pattern

The multifile input method lets you specify a camera, but PCOT still needs to be able to work out which filter was used to capture each band in the image. This is done by extracting the filter name or position from the filename using a regular expression (or regex). If you have some experience with regular expressions (or access to someone with this experience), it will help immensely.

Regular expressions describe patterns which texts might match. For example, the regex c[a-z]t will match any three-letter string starting with c and ending with t: it's c, followed by any character between a and z, followed by t.

• Beginner's guide
• Useful 'playground' to try out expressions

The default pattern looks something like this:

.*[LR]WAC(?P<pos>[0-9][0-9]).*

This means:

• .* matches any number of any character, so there could be anything at the start of the filename.
• [LR] means "either L or R".
• WAC means we must then have the sequence of letters WAC
• (?P<pos>[0-9][0-9]) means we must now match two digits ([0-9]). We've put them in brackets and preceded them with ?P<pos> which means we should store the result under the name pos.
• The final .* means that there can now be any number of any character again - so there could be anything at the end of the filename.

The idea is that a filename like /home/jim/files/DogBiscuitLWAC02Fish.jpg will be matched, and will result in 02 being stored as pos, which will then be used to look up the filter.

The default pattern can be set from the settings dialog.

Named matches and how they are used

Only one of the following should be true (e.g. you can't use name and n together):

• lens and n: if these are found, they are joined together to form a filter position which is looked up in the filter set (by the position "Pos" field). The idea is that lens indicates either the left or right camera and n identifies a filter. They're separate because many early files used names like LWAC02 or LWideAngle02, in which the two elements were separate. In many cases you'll want to use the pos option below.
• pos: if this is found, it us used to match a filter position using the position field - as such, it's a simpler version of the lens/n combination
• name: if this is found, it is used to match a filter using the filter's name
• cwl: if this is found, it is used to match a filter using the CWL (wavelength) field

Special handling for "lens/n" patterns

We often have filter positions like "L01" but filenames containing "...LWAC01..." or "...LWAC1..." with either leading zeroes or without. However, PCOT must consider them to be the same.

To make this happen, the comparison function for filter positions first checks that both strings - the filename match (e.g. "LWAC1") and the position name ("L01") - are a string of letters followed by a string of numbers. If they aren't, the filename match must be the same as the filter position.

If the two strings are in the appropriate form, they are split into two parts - the string and number sections. The string sections must be the same, but the number sections are compared after being converted to integers.

This is best explained by example. Consider the pattern

.*(?P<lens>[LR](WAC(?P<n>[0-9][0-9]).*

Here, lens can be either L or R, n is a sequence of digits. As described above, these are combined together to form a position, so "LWAC01" would become the position "L01". Given the following filenames, here are those which would match the filter position "L01":

filename	match	notes
LWAC01.png	yes	simplest form of match
8685-LWAC01-650.png	yes	lens=L, n=01
8745-LWAC01650.png	no	lens=L, n=01650
9384-LWAC1-foo.png	yes	lens=L, n=1, numerically equal to 01 in filter name

Missing filter data

When the system can't find suitable filters in the camera using this system, you'll get an error in the log, and also a warning in the canvas ("Missing filter data").

If you need assistance, or the pattern system isn't flexible enough, contact us - or maybe use the assignfilters node.

Assigning filters manually

Sometimes it's difficult to write a filter pattern to infer the filters automatically from the filename. In this case, you can assign filters in a camera to bands in an image manually using the assignfilters node (in the "utility" group). This is fairly self-explanatory: feed in an image, select a camera, and assign the bands using the move up and down buttons.

Reading raw binary files

Data is often provided "as is" from the camera, in a raw binary format. Reading these files requires a little more information in advance:

• What the numeric format of the data is (e.g. 16-bit unsigned integer)
• How big the image is in pixels
• Whether there is a header at the start which should be skipped and how big it is (the "offset")
• Whether the image needs to be rotated and/or flipped
• Whether the data is "big-endian" or "little-endian."

These can be set by clicking the "raw loader settings" dialog.

Missing files and directories

PCOT documents are often shared without the original source images, so it's common to open a .pcot file on a machine where the directory (or some of the files) the Multifile input was reading from no longer exists. This is not treated as an error - the document's cached image data is kept, and the graph carries on working with it.

If this happens, you'll see:

• The Multifile tab button gets a red border, and hovering over it shows a tooltip explaining what couldn't be found.
• A banner at the top of the Multifile tab itself describes the problem (a missing directory, or one or more missing files within it), and reassures you that cached data is still being used, so nothing is actually broken.
• In the file list, any files that couldn't be found are shown in red and moved to the top of the list, so they're easy to spot among a long list of otherwise-normal files.

The original directory/file path is never silently overwritten or reset to some other directory - it's left as configured, so you can fix the underlying problem (e.g. mount the drive, copy the files back) and try again.

Once the files are back in place, use the Retry missing inputs button in the main window to re-check all inputs and reload any that were previously missing, without needing to close and reopen the document.

Presets

You can save and load these values - and most other settings for multifile input, such as the pattern and filter - using the "Presets" button. Presets are currently stored in your home user directory in a file called MFPresets.json. Users can easily copy this file from other users.