Change Log

Table of Contents

Why is there a jump in version numbers?

There was a BASEmesh v2.1, but there never was a QGIS plugin built on that version. This jump keeps the QGIS and Python package versions aligned.

Targeted QGIS Versions

This release supports QGIS versions 3.10 LTR up to 3.26 (the latest stable release as of this writing).

The processing toolbox, elevation and quality meshing, and interpolation features were all tested in the following versions:

QGIS Version Codename Tested on
3.10 LTR A Coruña 3.10.14
3.16 LTR Hannover 3.16.16
3.22 LTR Białowieża 3.22.9
3.24 Tisler 3.24.1
3.26 Buenos Aires 3.26.3

Highlights

Changes

BASEmesh Core

Applicable to both the Python API and the QGIS plugin.

  • Meshes exported for BASEMENT 3 will now always contain a MATID. If no MATID was specified in the quality meshing step, an ID of 0 will be used. This resolves a display issue in QGIS 3.16+ which would mislabel element bed elevation as MATID based on the index.

  • The Triangle input and output files are once again placed a "triangle_tempfiles" subdirectory, rather than directly next to the generated mesh.

    Note: in the QGIS plugin, these files are only kept if the 'Keep tempfiles' flag is checked.

  • BASEmesh v2.2 uses a new Triangle wrapper and file parser that are more efficient when processing large files. This significantly reduces memory and CPU impact when generating quality meshes larger than 1'000'000 elements.

  • When opening legacy BASEMENT mesh files that do not contain a NUM_MATERIALS_PER_ELEM flag, the material count will instead be inferred from the first element encountered.

  • BASEmesh requires counter-clockwise vertex order on its elements for efficient element hit tests during interpolation. Elements are automatically flipped upon reading a mesh to abide by this. When this occurs, a warning will be raised to inform the user of the change.

  • BASEmesh now allows reading 2DM mesh files whose node or element ID ranges start at 0, the mesh will be converted to 1-based IDs automatically.

  • The geometry cleanup system has been redesigned to be more performant and scale better for large datasets. These performance improvements cover the geometry loading step, the geometry cleanup/conformation, and the generation of Triangle input geometries for meshing.

  • Node and element IDs are now automatically renumbered as they are read from Triangle. This should have no impact on existing workflows as Triangle picks arbitrary IDs.

  • The "Input nodes may not coincide" error message has been replaced with a non-fatal warning. This still points towards a triangulation error producing zero-area elements, but the output will now load into BASEmesh and QGIS to facilitate troubleshooting.

QGIS Plugin

Not applicable to the Python API.

  • A new checkbox has been introduced next to the 'Snapping tolerance' setting that allows users to completely disable all input cleaning in BASEmesh.

    This allows users to manually process their input data, rather than relying on the thorough but expensive logic BASEmesh uses. An example project using this functionality has been added to the repository Wiki: Mesh Generation with Building Outlines

    Note that enabling this option risks obscure Triangle errors that may be non-trivial to troubleshoot. To assist users wanting to make use of this new functionality, additional Wiki pages have been created:

    Even with these new resources, this remains an advanced feature. It is still recommended using the default input conformation wherever possible.

  • BASEmesh now supports automatic splitting of node strings into sub-strings as part of the quality meshing workflow. Node strings longer than this value will be separated into shorter segments, which are numbered automatically:

    Before:

    Input: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

    After conversion with limit=6:

    Input_01: 1, 2, 3, 4, 5, 6
    Input_02: 6, 7, 8, 9, 10

    The above is only for illustration, most versions of BASEMENT 3 require a setting of 40.

  • A mesh renumbering workflow has been added to the QGIS processing toolbox. This workflow will read meshes regardless of ID ordering or ID range gaps and save them as valid 2DM files. It optionally emits CSV files that track the old and new ID for any node and element in the mesh.

  • User-facing warnings, such as a hole marker being assigned a MATID, will now be forwarded to the QGIS GUI.

  • Custom mesh boundaries have been enabled for the BASEmesh plugin. A copy of the input polygon's edges will be merged into the break lines prior to meshing. After triangulation, any elements outside the original mesh domain will be deleted and the mesh renumbered.

    This feature should be considered experimental and requires additional processing after triangulation. For large meshes, this option may result in poor meshing performance.

  • Convex hull support is no longer on the roadmap for quality mesh generation.

    This option proved very unstable even with otherwise good input data, in ways that we could not handle on the BASEmesh side prior to sending the geometry to Triangle. As a result, we have removed the radio button from the GUI for the quality meshing dialog. Convex hulls are still available for elevation meshes.

    Note: If your use case requires convex hull, it can still be enabled using the c switch in the 'Extra arguments' field of the quality meshing tool.

  • Plugin load times have been improved significantly as resource and GUI components are now generated at plugin installation, rather than on load.

  • NULL values are now allowed for the dividing constraints field. A value of NULL, or any value less than 2, will not cause any subdivision of the break line.

BASEchange

  • The CSV input file format now has full control over all cross-section parameters, including channel height and bank slope.

    With this, all cross-section parameters are generated on the fly when using CSV input:

    Identifier Parameter Unit
    bed_width Bed width [m]
    height Elevation of the crest over the channel bed [m]
    bank_slope Rise-over-run slope of the channel banks [-]
    midpoint_shift Relative position of the intermediate node of the channel banks, between 0 and 1 [-]
  • Accessing the BASEchange mesh generator through the BASEmesh namespace is deprecated and will be removed in upcoming versions. Please update your code and command line calls to access BASEchange directly:

    # Deprecated
    python -m basemesh.basechange <...>
    
    # Recommended
    python -m basechange <...>

Python API

These changes only affect users of the "basemesh" Python package, rather than the plugin.

  • The BASEmesh package now requires Python v3.8 or greater.

  • The BASEchange and MeshTool utilities may be moved out of the BASEmesh namespace in a future version of the plugin. Starting with BASEmesh v2.2, they are installed as standalone modules, rather than submodules of BASEmesh.

    # Old syntax, deprecated
    from basemesh import basechange
    
    # Recommended
    import basechange
    import meshtool
  • In previous versions of BASEmesh, running without C extensions installed would generate a "No compatible C extensions found, ..." warning.

    This has been removed. Instead, users may access the basemesh.algorithms.implementation attribute to detect the active implementation as either c or py.

  • A Sphinx configuration for building the Python API docs as an HTML page has been added to the docs/ directory of the repository.

    These docs are currently not hosted on other sites and must be built locally:

    1. Clone the BASEmesh repository
    2. Run python -m pip install --user -r docs/requirements.txt
    3. Run cd docs/
    4. Run python -m sphinx.cmd.build -b html . _build -n -a
    5. Open the built documentation at docs/_build/index.html in a browser

Bug fixes

  • Fixed an issue that caused the node IDs in string def text files for BASEMENT 2 to be offset by one if the input mesh was converted from a zero-based Triangle mesh.

  • Resolved an issue that could cause the GUI feedback reporting (e.g. progress bar) to freeze during long-running operations.

  • Fixed an issue in BASEchange's TrapezoidalChannelWidening factory that would use the global bed friction for the widening, rather than the widened section's bed friction.

    Other channel factories and the CSV file import are not affected.

Known issues

We are not aware of any known issues with this version. Please report any issues in the BASEMENT User Forum.

Installation

This release is available in the BASEmesh plugin repository. Alternatively, you can download the archive below and install it manually using the "Install from ZIP" option in the Plugin Manager:

basemesh_v2-2-0.zip