# xtrack-format v3.2.3

**Mercurial revision 5786:5c8b45563631 | 2026-08-04**

---

## Description

`xtrack-format` is a tool designed to **convert native along-track altimetry data** from the **CTOH native format** to the **XTRACK format**. This allows for standardized processing and analysis of altimetry data.

---

## Usage

```bash
xtrack-format [OPTIONS]
```

---

## Options


| Option            | Description                                                                                |
| ----------------- | ------------------------------------------------------------------------------------------ |
| `-h`, `--help`    | Display this help message and exit.                                                        |
| `-c <convention>` | Convention to read all track files. **Default:** `track-raw.TPJ1`.                         |
| `-p <path>`       | Path to the directory containing the track files.                                          |
| `-z <num>`        | Pre-set number to activate zonal crop. See [Zones](#zones) for details. **Default:** `-1`. |


> **Note:** The `-o` option (output file) is **deprecated** and no longer supported.

---

(zones)=
## Zones {zones}

If the `-z <num>` option is activated, the program will look for the following files in the current directory to determine the track numbers for the specified zone:


| Zone Number | File                     |
| ----------- | ------------------------ |
| `-1`        | `traces.txt`             |
| `0`         | `traces_ctoh_NEA.txt`    |
| `1`         | `traces_ctoh_MED.txt`    |
| `2`         | `traces_ctoh_ATLSUD.txt` |


> **Warning:** The `traces.txt` files contain all the track numbers for a dedicated zone. Currently, **no automated function based on frame is implemented**.

---

## Examples

### **Basic Conversion**

Convert track files using the default convention (`track-raw.TPJ1`):

```bash
xtrack-format -p /path/to/track/files
```

### **Specify a Custom Convention**

Convert track files using a custom convention:

```bash
xtrack-format -c track-raw.TPJ2 -p /path/to/track/files
```

### **Use a Specific Zone**

Convert track files for the **Mediterranean zone** (`1`):

```bash
xtrack-format -z 1 -p /path/to/track/files
```

### **Use the Default Zone**

Convert track files using the default zone (`-1`):

```bash
xtrack-format -z -1 -p /path/to/track/files
```

### **Full Example**

Convert track files for the **North East Atlantic zone** (`0`) with a custom convention:

```bash
xtrack-format -c track-raw.TPJ1 -z 0 -p /path/to/track/files
```

---

## Environment Variables

`xtrack-format` does not use any specific environment variables. However, ensure that:

- The **input path** (`-p`) is accessible and contains the required track files.
- The **zone files** (e.g., `traces.txt`, `traces_ctoh_NEA.txt`) are present in the current directory if using the `-z` option.

---

## Notes

1. **Input Files:**
  - The tool expects track files in the **CTOH native format**.
  - The `-p` option must point to a directory containing these files.
2. **Zones:**
  - The `-z` option requires the corresponding zone file (e.g., `traces_ctoh_MED.txt` for `-z 1`) to be present in the current directory.
  - If no zone is specified (`-z -1`), the tool will use `traces.txt` by default.
3. **Output:**
  - The output files are generated in the **XTRACK format** and saved in the current directory (`./`).
  - The output convention is set to `track-ref.TP+J1` by default.
4. **Deprecated Options:**
  - The `-o` option (output file) is **no longer supported**. Output is always written to the current directory.

---

## See Also

- [CTOH (Centre de Topographie des Océans et de l'Hydrosphère)](https://ctoh.legos.obs-mip.fr/)
- [XTRACK Format Documentation](https://ctoh.legos.obs-mip.fr/products/xtrack/)