# topo\_smooth v3.2.3

**Mercurial revision 5827:6131e4c94bf4 | 2026-09-18**

---

## Description

`topo_smooth` is a tool designed to **smooth bathymetry data** (either globally or within a specified polygon) using **median** or **LOESS** filters. It allows for fine-tuning of depth values and scaling adjustments to refine the bathymetric surface.

---

## Usage

```bash
topo_smooth [OPTIONS] -b <bathymetry_file>
```

---

## Options

### **Input/Output Options**


| Option                        | Description                                                             |
| ----------------------------- | ----------------------------------------------------------------------- |
| `-h`, `--help`                | Display help and exit.                                                  |
| `-b <file>`                   | **Required.** Path to the input bathymetry file.                        |
| `-o <rootname>`               | Output rootname (default: `out`).                                       |
| `-f <format>`, `-oF <format>` | Output format: `grd`, `grd-float`, `nectdf`, or `xyz` (default: `grd`). |


---

### **Filtering Options**


| Option                    | Description                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------- |
| `-p <file>`               | Path to a **closed polygon file** defining the area where the filter will be applied. |
| `--filter=[median|loess]` | Choose the smoothing filter: `median` or `loess` (default: `loess`).                  |
| `-r <radius>`             | Radius of the filter (in degrees).                                                    |


---

### **Depth Adjustment Options**


| Option            | Description                                                                             |
| ----------------- | --------------------------------------------------------------------------------------- |
| `-zmin <depth>`   | Minimum depth for filtered bathymetry (default: `-500`).                                |
| `-zmax <depth>`   | Maximum depth for filtered bathymetry (default: `0`).                                   |
| `-inv`            | Invert depth/altitude on the selected area. Equivalent to `-scale -1`.                  |
| `-scale <factor>` | Scale factor to apply on the selected area and smooth edges to merge with surroundings. |


> **Note:** `-inv` and `-scale` **cannot** be used together. The last one specified will override the previous.

---

## Examples

### **Basic Smoothing with LOESS Filter**

Smooth the entire bathymetry file using the default LOESS filter:

```bash
topo_smooth -b bathymetry.grd
```

### **Smooth a Specific Polygon Area**

Apply LOESS smoothing to a specific polygon area:

```bash
topo_smooth -b bathymetry.grd -p polygon.txt -r 0.1
```

### **Smooth with Median Filter**

Use the median filter for smoothing:

```bash
topo_smooth -b bathymetry.grd --filter=median -r 0.05
```

### **Set Depth Range for Smoothing**

Smooth only depths between `-1000` and `-100` meters:

```bash
topo_smooth -b bathymetry.grd -zmin -1000 -zmax -100
```

### **Invert Depth Values**

Invert depth/altitude values in the selected area:

```bash
topo_smooth -b bathymetry.grd -p polygon.txt -inv
```

### **Scale Depth Values**

Apply a scale factor of `1.5` to the selected area:

```bash
topo_smooth -b bathymetry.grd -p polygon.txt -scale 1.5
```

### **Custom Output Format and Rootname**

Save the smoothed bathymetry in `xyz` format with a custom rootname:

```bash
topo_smooth -b bathymetry.grd -o smoothed_bathy -f xyz
```

### **Combine Filtering and Depth Range**

Apply a median filter with a radius of `0.2` degrees and restrict smoothing to depths between `-2000` and `-50`:

```bash
topo_smooth -b bathymetry.grd --filter=median -r 0.2 -zmin -2000 -zmax -50
```

---

## Environment Variables

`topo_smooth` does not rely on specific environment variables. However, ensure your system has sufficient **memory** and **disk space** for large bathymetry files.

---

## Notes

1. **Input File:**
  - The `-b` option is **mandatory** to specify the input bathymetry file.
2. **Polygon File:**
  - The polygon file (`-p`) must define a **closed polygon** (e.g., a shapefile or ASCII file with coordinates).
3. **Filter Selection:**
  - The default filter is **LOESS**. Use `--filter=median` to switch to median filtering.
4. **Depth Range:**
  - The `-zmin` and `-zmax` options define the depth range for filtering. Values outside this range will not be smoothed.
5. **Scaling and Inversion:**
  - `-inv` and `-scale` are **mutually exclusive**. The last one specified will override the other.
  - `-inv` is equivalent to `-scale -1`.
6. **Output:**
  - If no output rootname (`-o`) is provided, the default is `out`.
  - Supported output formats: `grd`, `grd-float`, `nectdf`, `xyz`.
7. **Deprecated Options:**
  - Previously, adding a file to the command without options was interpreted as a trusted bathymetry file for outlier removal. **This is no longer supported.**

---

## See Also

- [NetCDF Tools](https://www.unidata.ucar.edu/software/netcdf/) (for `nectdf` format)
- [Generic Mapping Tools (GMT)](https://www.generic-mapping-tools.org/) (for `grd` and `xyz` formats)