Have a question?


How to use Crayfish

Crayfish 2.0

What is Crayfish?

Crayfish is a plugin (extension) developed by Lutra Consulting for the free and open source GIS platform QGIS.

The Crayfish plugin aspires to be a complete set of tools to visualise temporal data.

Crayfish toolbar
  1. Contour/vector overlay lock, plot option and grid calulator
    1. : to be able to overlay vectors and grids from different quantities
    2. : to generate plot from the selected quantity
    3. : grid calculator
  2. Quantity layer tree: switch between active quantities
  3. Time control / slider
    1. :Time settings to switch between relative/absolute time and different time formats
  4. Contour settings: Changing grid symbology
  5. Vector properties: Changing vector symbology
  6. Disable/enable mesh: To view mesh and label the mesh items
  7. Active grid values


From QGIS Plugin Repository

Crayfish can be installed from QGIS repository. It requires binary libraries specific to your platform. We distribute Windows (32-bit and 64-bit) DLL files, Linux libraries (64-bit) for Debian and Fedora-based distributions (Ubuntu, Debian, Linux Mint, Fedora etc). If your operating system is one of these, the plugin should automatically download the required libraries.

If you have problems downloading the binary files, it is likely caused by your proxy server. You can download the files manually and place them under your plugin folder. Make sure you choose the right binaries for your platform. For DLL files you can click here and for ffmpge click here to download the zip files from our server.

From source

Instructions for compiling the latest version of source code can be found on the github repository.

Loading data

Sample data

You can download and use this example dataset to follow the rest of the tutorial on this page. The data are in EPSG:27700 and represent depth and velocity for a dummy event. Please note that the results are based on dummy data and do not represent any calculated or real flood risk.

Once Crayfish is installed, a new icon Crayfish viewer data should be added to your Layers toolbar. To open a set of results, either use the Add Crayfish Layer button Crayfish viewer data on the Manage Layers toolbar or select Crayfish > Add Crayfish Layer from the main Plugins menu. You should now be presented with the Open Crayfish File Dialog.

From here you can either load a mesh file (.2dm) or a results files (.dat or .sol). Crayfish requires projection of the layers to load them into QGIS. If there is a .prj file within the same folder of the mesh file, Crayfish will use the projection information from the .prj file. Otherwise, it will assign a projection based on user’s settings.

The appropriate mesh file should be loaded automatically when the user opens a .dat file. If mesh file has different name, users can locate the mesh file manually.

If a quantity contains time-varying data, you will be able to browse through outputted times and change the timing through the time control. Some quantities may contain subsets of values. In example above, Maximums are shown as a subset of depth and velocity quantities.

To view the underlying mesh of the outputted data, you can activate mesh shown on item 6 of the Crayfish viewer dock.

Vector and contour overlay

Quantities may contain contour only, or contour and vector data. In the example below, depth contains only contour values, whilst velocity contains both contour and vector. By default, Crayfish renders contours and vectors from the same quantity. For example in the figure above, you can see velocity contours and velocity arrows. If you want to see contours and vectors from different quantities, you need to "unlock" the contour/vector overlay (see item 2 in the Crayfish toolbar).

The video below demonstrates how to overlay vectors from velocity on top of depth contours:

Styling data


Styling of contours can be done either through the Basic settings or the Advanced settings. The basic settings option allows users to quickly change the colour profile, minimum and maximum extents and transparency. For advanced options, click on the setting icon and a new window will appear.

Advanced contour settings

Through this window you can:

  • Create your own colour ramp
  • Change values and labels
  • Set the interpolation in the colour ramp
  • Save and load colour settings
  • Fill values above or below the min/max


Vector styling can be done through the vector setting dialogue window.

Vector settings

Under Arrow Length, you can set the shaft length based on min/max values, scaled or fixed.

You can set an arbitrary grid, where vectors will be displayed by activating Display Vectors on User Grid. This is particularly useful to view a smoother vector interpolation, when the outputted vectors are on a coarser grid.

You can also set a filter to display vectors above/below certain values.

To display vectors as streamlines or traces, you can select the option for streamlines and fill in the relevant parameters accordingly.

Query data


Values of mesh and the active layer on the quantities are shown on item 7 of the Crayfish viewer dock. In the example above Elevation and Velocity values are shown.


Users can generate plots of time series at a point or a cross section in Crayfish. In example below, we are going to visualise the time series for depth from the example dataset provided in the section above.

  • Start a new QGIS session and add ivs_001_d.dat Crayfish layer
  • From the Crayfish panel, click on Plot, a new panel will appear
  • For Layer, Select ivs_001
  • For Plot, Select Time series
  • For Dataset, Select current
  • Select From map
  • Press CTRL key from your keyboard if you want to add more points

As you move the mouse, the time series plot gets updated until you click on the map.

Depth time series plot

Depth time series plot (Click to enlarge).

To plot cross sections or time series from an existing line or point vector layer loaded in QGIS, you need to click on From Layer and select the layer first. You can then use the select tool Select tool from the main QGIS toolbar to display plot for each feature.

You can change various settings of the plot by right-clicking on the plot area. Crayfish plot also supports export to the following formats: image (png, jpg, etc.), scalable vector graphics and CSV.

Processing tools


Crayfish comes with a set of tools integrated to processing framework. To use these tools, you need to activate Crayfish provider in Processing options. From the main menu, select Processing > Options and in the new window, under Providers > Crayfish algorithms select the option for Activate.

Crayfish in the Processing Toolbox

Integrated algorithms

  • Export grid
  • Export contours
  • Export mesh elements
  • Export mesh nodes
  • Mesh statistics
  • Render bed elevation

With the integration of Crayfish modules within the Processing Toolbox, users can automate and batch process Crayfish layers. As an example, you can export multiple Crayfish layers to Geo-TIFF using the Processing Toolbox.

Grid Calculator

Grid calculator will allow users to generate derived data based on the existing quantities. To use the grid calculator click on Grid calculator from the top of the Crayfish panel. A new window will appear:

Crayfish Grid Calcultor
  • Datasets:will list the available datasets to use for calculations
  • Result layer:path to store results. The output is currently saved in XMS binary dat format
  • Spatial filter:will limit the calculation to the bounding box. By default, it is set to the current layer extent.
  • Time filter:will limit the calculation to a subset of time range
  • Operators:list of available operators to construct an expression
  • Expression:the string containing quantities name and operators

Example expressions

Below are some examples of using operators:

  • if ( A>0.02 , A , NODATA ) creating a mask for values above 0.02 from layer A
  • max ( A , B ) will compare datasets A and B and outputs the maximum values between the two datasets as the result layer.
  • average_aggr ( A ) generates a dataset by calculating average values of A layer over time. The output will not have time dimension.

Exporting data

Export to raster

You can export contour data to raster by right clicking on the contour quantity. The export tool, will resample the result at the active time-based on the desired output resolution. The outputted raster format is in Geo-TIFF format.

Export contours

You can export contours to vector by right clicking on the contour quantity. The export contours tool, will resample the result at the active time-based on the desired output resolution and create contour lines or areas based on current colour scheme or user defined interval. The outputted vector format is in ESRI Shapefile.

Creating animation

You can create animations of the contours and vectors in the Crayfish layers. To generate an animation of contours and/or vectors, first you need to select the layer from QGIS layer tree. In QGIS, from the main menu, select Plugins, Crayfish and Export to animation.

A new window will appear:

  • General: to set the output frame size, frame rate, start and end time, output location file. Note that the frame size is only used with the Default layout.
  • Layout: Allows user to set layouts using Default layout or Custom layout
  • Video: Set video resolution and path to the video maker software (ffmpeg).

Users have 2 options for setting up video layouts.

Default layouts

For this option, users can set title, time and legend within this sections. For each item, users can set font size, font colour and item's background colour. You can also set the location where time and legend appear on the layout.

Custom layout (qpt)

Using a print composer template gives users options to set very flexible and customised layout. You can add multiple map views, overviews, shapes, etc. in the same way you'd produce a printed output.

For output time to appear on the layout, you need to add a text item and set the Item ID under Item properties in the print composer as time.