mesh-limits v3.2.3¶

Mercurial revision 5803:7164e00e8f3d | 2026-08-18

Description¶

mesh-limits is a tool designed to create model limits for mesh generation. It processes input files (such as shorelines, polygons, or existing limits) to define the boundaries of a computational domain, which can then be used for mesh generation in ocean modeling or other applications.

Usage¶

mesh-limits [OPTIONS] input

Options¶

General Options¶

Option	Description
`-h`, `--help`	Display help and exit.

Input/Output Options¶

Option	Description
`input`	Input file (e.g., shoreline file, polygon file, or existing limits file).
`-a <file>`	Path to a pre-existing open limits file (for use with `mesh-split`/`mesh-assembly`).
`-b <file>`	Path to a pre-processed limits file (for post-processing only). Disables `--extract`, `--smooth`, and `--limits`.
`-c <file>`	Path to a template criteria file for mesh generation.
`-p <file>`	Path to a domain polygon file.
`-o <file>`	Path to the output file. Default: Derived from the input file and output format.
`-s <file>`	Path to a raw shoreline file.
`-z <zone>`	Specify a zone (overrides `--point`).
`-I <format>`	Input file format. Default: Inferred from the file extension.
`-O <format>`	Output file format. Default: Inferred from the file extension.

Processing Options¶

Option	Description
`--frame <frame>`	Delimiting rectangular frame (e.g., `--frame "xmin,ymin,xmax,ymax"`).
`--extract`	Extract shorelines from the input. Disabled by `-b`.
`--sampling <value>`	Deprecated. Use `--sampling-length` instead.
`--sampling-length <value>`	Resolution of the output in meters (default: `5000`).
`--subsampling_level <level>`	Subsampling level for small objects. Range: `-1` (default, not optimal) to `5` (finer). Recommended: `2`.
`--rootname <name>`	Root name for intermediate output files (default: `anonymous`).
`--point <lon;lat>`	Coordinates of an ocean point inside the domain (e.g., `--point "-5;48"`).
`--resolution <polygons.nei values.dat>`	Paths to polygon files (`.nei` format) and values files for variable resolution. Example: `--resolution "../resolution.nei ../resolution.dat"`.
`--debug`	Enable debug outputs.
`--smooth`	Smooth the shoreline. Disabled by `-b`.
`--limits`	Build model limits. Disabled by `-b`.
`--adjust`	Adjust coastal resolution to fit neighboring open limits (for assembly with pre-existing open limits).
`--lake`	Use for non-open sea shorelines (e.g., lakes).
`--isocontour <value>`	Target isovalue for shoreline smoothing (optimal: `-1`, default: `-0.4`, max: `<1`).

Advanced Options¶

Option	Description
`-r <resolution>`	Background smoothing grid resolution in meters (default: `1/4` of `-l`, i.e., `625m` when `-l` and `--sampling-length` are at defaults).
`-l <length>`	Smoothing length in meters (default: `1/2` of `--sampling-length`, i.e., `2500m` when `--sampling-length` is at default).

Examples¶

Basic Usage with Polygon and Shoreline¶

Create model limits using a polygon file and a shoreline file, with an ocean point:

mesh-limits -p test.scan -s world-shoreline.shp --point '[-5;48]'

Extract Shorelines¶

Extract shorelines from a raw shoreline file:

mesh-limits -s world-shoreline.shp --extract --point '[-5;48]'

Smooth Shorelines¶

Smooth shorelines with a custom sampling length and smoothing:

mesh-limits -s world-shoreline.shp --sampling-length 2000 --smooth --point '[-5;48]'

Use Pre-Existing Open Limits¶

Use a pre-existing open limits file for assembly:

mesh-limits -a open_limits.plg -p domain_polygon.scan --adjust

Variable Resolution¶

Use variable resolution with polygon and value files:

mesh-limits -p domain_polygon.scan --resolution "resolution.nei resolution.dat" --point '[-5;48]'

Frame-Based Limits¶

Define limits using a rectangular frame:

mesh-limits --frame "-10,40,10,50" --sampling-length 1000 --point '[-5;48]'

Lake Mode¶

Create limits for a lake (non-open sea):

mesh-limits -p lake_polygon.scan -s lake_shoreline.shp --lake --point '[2;45]'

Custom Isocontour¶

Use a custom isocontour value for shoreline smoothing:

mesh-limits -s world-shoreline.shp --isocontour -0.2 --point '[-5;48]'

Output to Specific File¶

Save output to a specific file:

mesh-limits -p test.scan -s world-shoreline.shp -o output_limits.plg --point '[-5;48]'

Environment Variables¶

mesh-limits does not rely on specific environment variables. However, it may interact with system-level configurations for file paths or parallel processing if integrated with other tools.

Notes¶

Input Files:

The input file can be a shoreline file, polygon file, or an existing limits file.
If no input file is provided, shorelines will be extracted from the default shoreline database (/home/data/shorelines/gshhs-2.2/gshhs_f.cst).

Output Files:

The output file format is inferred from the extension (e.g., .plg, .scan, .shp).
Intermediate files (e.g., smoothed shorelines, resampled boundaries) are saved with the --rootname prefix.

Shoreline Extraction:

Use --extract to extract shorelines from a raw shoreline file.
Extracted shorelines are saved to a file named <rootname>-shoreline-extraction.plg.

Smoothing:

Smoothing is applied to filter sub-scale details and aggregate small structures.
The smoothing length (-l) and background grid resolution (-r) can be adjusted for finer control.

Model Limits:

Model limits are built from shorelines and selection polygons.
Ocean sections are flagged as 'M', while coastal sections are flagged as 'T'.

Assembly:

Use -a to assemble newly created model boundaries with pre-existing open limits.
The --adjust option ensures coastal resolution matches neighboring open limits.

Variable Resolution:

Use --resolution to specify polygon and value files for variable resolution sampling.
This is useful for domains requiring non-uniform mesh resolution.

Debugging:

Use --debug to enable debug outputs, which can help diagnose issues with shoreline extraction or limit generation.

Deprecated Options:

--sampling is deprecated. Use --sampling-length instead.