pyissm.tools.exp

Tools working with *.exp files for ISSM model domains and contours.

Functions

exp_read(filename)

Read contours from an exp file.

exp_to_shp(exp_filename, shp_filename)

Convert an Argus (.exp) file to a shapefile (.shp).

exp_write(contours, filename)

Write contours to an exp file.

gdf_to_exp(gdf, exp_filename)

Convert a GeoDataFrame to an Argus .exp file.

isoline(md, field[, value, output, edges, amr])

ISOLINE - construct isovalue lines based on field provided

shp_to_exp(shp_filename, exp_filename)

Convert a shapefile (.shp) to an Argus (.exp) file.
pyissm.tools.exp.exp_read(filename)

Read contours from an exp file.

This function reads contour data from a file in *.exp format. The function can handle files containing multiple contours. Each contour is returned as a dictionary containing coordinate data, metadata, and geometric properties.

Parameters:

filename (str) – Path to the input exp file

Returns:

contours – List of contour data read from the file. Each contour dictionary contains: - ‘x’ : np.ndarray

X coordinates of the contour points

  • ’y’np.ndarray

    Y coordinates of the contour points

  • ’name’str

    Name of the contour from the file

  • ’density’float

    Density value for the contour

  • ’nods’int

    Number of nodes/points in the contour

  • ’icon’str, optional

    Icon value from the file, if present

  • ’closed’bool

    Whether the contour is closed (first and last points are identical)

Return type:

list of dict

Raises:

IOError – If the input file does not exist

Notes

The function expects exp files with specific formatting including contour headers, point counts, density values, and coordinate data. The function handles variations in header spacing (e.g., ‘# Points Count Value’ vs ‘# Points Count Value’). Invalid formatting may cause parsing errors.

Examples

>>> contours = exp_read('input.exp')
>>> print(f"Read {len(contours)} contours")
>>> for contour in contours:
...     print(f"Contour '{contour['name']}' has {contour['nods']} points")
pyissm.tools.exp.exp_to_shp(exp_filename, shp_filename)

Convert an Argus (.exp) file to a shapefile (.shp).

The function reads contours from the input exp file and converts them to geometries in a shapefile format. Supported geometry types include Point, LineString, and Polygon based on the number of points and closed flag in the exp contours. Each geometry in the shapefile will include attributes such as name and density from the exp file. The function performs error checks on file existence and extensions before processing.

Parameters:

  • exp_filename (str or Path) – Input exp file.

  • shp_filename (str or Path) – Output shapefile.

Return type:

None

pyissm.tools.exp.exp_write(contours, filename)

Write contours to an exp file.

This function writes contour data to a file in *.exp format. The function can handle both single contours and lists of contours. Each contour should be a dictionary containing ‘x’ and ‘y’ coordinate data, and optionally ‘name’ and ‘density’ fields.

Parameters:

  • contours (dict or list of dict) –

    Contour data to write. If a dictionary, represents a single contour. If a list, represents multiple contours. Each contour dictionary should contain: - ‘x’ : array-like or scalar

    X coordinates of the contour points

    • ’y’array-like or scalar

      Y coordinates of the contour points

    • ’name’str, optional

      Name of the contour. If not provided, filename is used

    • ’density’int, optional

      Density value for the contour. Default is 1.0

  • filename (str) – Path to the output exp file

Raises:

RuntimeError – If X and Y coordinates are not of identical size

Notes

The exp file format includes headers with contour names, point counts, density values, and coordinate data formatted to 10 decimal places.

Examples

>>> contour = {'x': [0, 1, 2], 'y': [0, 1, 0], 'name': 'triangle'}
>>> exp_write(contour, 'output.exp')
>>> contours = [
...     {'x': [0, 1], 'y': [0, 1], 'density': 2},
...     {'x': [2, 3], 'y': [2, 3], 'name': 'line2'}
... ]
>>> exp_write(contours, 'multiple_contours.exp')
pyissm.tools.exp.gdf_to_exp(gdf, exp_filename)

Convert a GeoDataFrame to an Argus .exp file.

The function reads geometries from the input GeoDataFrame and converts them to contours in the exp file format. Supported geometry types include Point, LineString, MultiLineString, Polygon, and MultiPolygon. Each contour in the exp file will include coordinate data and optional attributes such as name and density. The function performs error checks on file existence and extensions before processing.

Parameters:

  • gdf (GeoDataFrame) – Input GeoDataFrame containing geometries to convert to exp format.

  • exp_filename (str or Path) – Output exp filename. Must have .exp extension.

Return type:

None

pyissm.tools.exp.isoline(md, field, value=0.0, output='struct', edges=None, amr=None)

ISOLINE - construct isovalue lines based on field provided

Usage:

contours, edges_tria = isoline(md, field, value=0.0, output=”struct”, edges=None)

Supported options (MATLAB parity):

value : isoline value (default 0) output : “struct” (default), “matrix”, “longest”, or “filename.exp” edges : if provided, reuse precomputed edges_tria (2D mapping) amr : optional object overriding x/y/elements: amr.MeshX, amr.MeshY, amr.MeshElements

Returns:

list of dicts (exp-struct-like) OR an (N,2) array if output=”matrix” edges_tria : (nE,3) int array mapping each triangle to its unique-edge ids

Return type:

contours

pyissm.tools.exp.shp_to_exp(shp_filename, exp_filename)

Convert a shapefile (.shp) to an Argus (.exp) file.

The function reads geometries from the input shapefile and converts them to contours in the exp file format.

Parameters:

  • shp_filename (str or Path) – Input shapefile.

  • exp_filename (str or Path) – Output exp filename.

Return type:

None