# map-converter v3.2.3

**Mercurial revision 5770:c90c3015e72d | 2026-05-22**

---

## Description

`map-converter` is a tool designed to **convert the format of topographic files**. Currently, it supports **IGN ASCII files** as input and converts them to **NetCDF** and **GDR** formats.

---

## Usage

```bash
map-converter [OPTIONS] file
```

---

## Options


| Option                  | Description                                                                              |
| ----------------------- | ---------------------------------------------------------------------------------------- |
| `-h`, `--help`          | Display help and exit.                                                                   |
| `-inv`, `-inverse`      | Invert the topography (multiply by `-1`).                                                |
| `-scale <value>`        | Apply a scaling factor to the topography (GDR format only).                              |
| `-mask <value>`         | Set the mask value for the topography.                                                   |
| `--proj=<proj4_string>` | Convert Cartesian coordinates to spherical coordinates using the provided PROJ.4 string. |
| `-o <rootname>`         | Set the root name for the output file(s).                                                |
| `-v <name>`             | Set the variable name for the output.                                                    |


---

## Deprecated Options

> **Warning:** These options are **deprecated** and may not be supported in future versions.


| Option         | Description                                            |
| -------------- | ------------------------------------------------------ |
| `-b <file>`    | Path to the bathymetry file.                           |
| `-p <file>`    | Path to the polygon file to limit the conversion area. |
| `-iF <format>` | Input format (no longer required).                     |
| `-oF <format>` | Output format (no longer required).                    |


---

## Examples

### **Basic Conversion**

Convert an IGN ASCII file to NetCDF:

```bash
map-converter input.xyz -o output
```

### **Invert Topography**

Invert the topography values (multiply by `-1`):

```bash
map-converter input.xyz -inverse -o output
```

### **Apply Scaling Factor**

Apply a scaling factor of `10.0` to the topography (GDR format):

```bash
map-converter input.xyz -scale 10.0 -o output
```

### **Set Mask Value**

Set a custom mask value (e.g., `9999.0`):

```bash
map-converter input.xyz -mask 9999.0 -o output
```

### **Convert Cartesian to Spherical Coordinates**

Convert Cartesian coordinates to spherical using a PROJ.4 string:

```bash
map-converter input.xyz --proj="+proj=longlat +datum=WGS84" -o output
```

### **Set Variable Name**

Set a custom variable name (e.g., `elevation`):

```bash
map-converter input.xyz -v elevation -o output
```

### **Full Conversion Example**

Convert an IGN ASCII file to NetCDF with inverted topography, scaling, and a custom variable name:

```bash
map-converter input.xyz -inverse -scale 10.0 -v elevation --proj="+proj=longlat +datum=WGS84" -o output
```

---

## Environment Variables

`map-converter` does not rely on specific environment variables. However, if you are using **PROJ.4** for coordinate transformations, ensure that the `PROJ_LIB` environment variable is set correctly to locate PROJ.4 data files.

---

## Notes

1. **Input File Format:**
  - Currently, only **IGN ASCII files** are supported as input.
2. **Output Formats:**
  - The tool generates **NetCDF** and **GDR** files by default.
  - The output file name is constructed using the root name provided with `-o`.
3. **Mask Handling:**
  - The `-mask` option allows you to define a value that represents missing or invalid data in the input file.
4. **Coordinate Conversion:**
  - Use `--proj` to convert Cartesian coordinates to spherical coordinates. The PROJ.4 string must be valid.
5. **Topography Inversion:**
  - The `-inverse` or `-inv` option is useful for converting between **elevation** and **depth** (bathymetry).
6. **Scaling:**
  - The `-scale` option is only applicable for **GDR** output format.

---

## See Also

- [PROJ.4 Documentation](https://proj.org/) (for coordinate transformations)
- [NetCDF Format](https://www.unidata.ucar.edu/software/netcdf/) (for output file specifications)