@@ -36,6 +36,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Fixed
 
+- **Native 3-D files: the vertical axis is now preprocessed like the horizontal plane.** `z` was laid out and then left raw, so a smoothed x/y was combined with an unsmoothed z in IL-16 and IL-17 and no setting could reduce the vertical share of the 3-D path. It now goes through the same steps and settings as x/y: blanked where a jump was replaced, bridged across tracking intervals, gap-filled (same `max_gap_frames`, same limits) and smoothed (same method, window and polyorder). On a synthetic helix with 2 mm noise (true 3-D path 251.5 cm, true vertical path 15.96 cm) the vertical contribution to IL-16 was 129.14 cm at every smoothing setting; it is now 60.09 cm at window 5 (default) and 16.49 cm at window 41, and IL-16 is 275.78 cm and 252.06 cm (was 307.66 and 294.20). **Native 3-D IL-16 and `max_speed_3d_cm_s` will be lower than before on noisy files**; the sensitivity sweep now varies the vertical half too. Cached preprocessing is rebuilt once (cache schema 7); `project_hash` is unchanged.
 - **idtracker.ai bare exports.** A CSV bundle written without a time column (idtracker.ai omits it when the frame rate is unknown) no longer crashes with a bare `ValueError`: the column count decides whether a leading time column is present, for `trajectories.csv` and `id_probabilities.csv` alike. `id_probabilities` that do not match the trajectories (frames or animals) are now refused with `IDT_SHAPE_MISMATCH` instead of passing silently. The idtracker.ai reader gains optional `fps`, `width_px` and `height_px` options for exports that record no video size or frame rate; they fill gaps only, behind the trajectory file and `session.json`. A folder whose only trajectory format is a pickle and has no consent now fails with `IDT_PICKLE_REFUSED` (was `IDT_FORMAT_AMBIGUOUS`).
 - **The test run no longer crashes at exit, and runs about three times faster.** After every test had passed, the Qt
   tests intermittently ended with "QObject: shared QObject was deleted directly" and a segfault (exit 139), which
 
@@ -182,6 +182,12 @@ def test_il15_with_the_water_column_counts_the_outside_values(
     their depth is NaN and they are counted, never clipped: 2 of 11 outside; the other nine
     frames (z 10 to 19.6) average 14.8 cm = 0.74."""
     manifest = _manifest(project, WaterColumn(surface_z=0.0, floor_z=20.0))
+    # the scene sits exactly on the surface (z = 0 at frame 0); smoothing's rounding noise
+    # (-3e-16) would put that one sample outside, which is not what this test is about
+    no_smoothing = manifest.preprocess.smoothing.model_copy(update={"enabled": False})
+    manifest = manifest.model_copy(
+        update={"preprocess": manifest.preprocess.model_copy(update={"smoothing": no_smoothing})}
+    )
     Engine(manifest).run(tmp_path / "o", exporters=["csv_long", "csv_wide"])
     one = _long(tmp_path / "o", "fish1")
     assert _value(one, "IL-15", "mean_depth_fraction") == pytest.approx(0.3, abs=1e-9)
 
@@ -108,12 +108,13 @@ def test_pipeline_lays_out_z_with_xy() -> None:
     assert psess.separator_mask.any()
     assert np.isnan(psess.z[psess.separator_mask]).all()
     assert gap.raw_z is not None
-    np.testing.assert_array_equal(psess.z[psess.tracked_mask], gap.raw_z)
+    # z now goes through the same smoothing as xy; a straight line is unchanged by it
+    np.testing.assert_allclose(psess.z[psess.tracked_mask], gap.raw_z, atol=1e-9)
 
     whole = _session_z(None)
     plain = run(whole, PreprocessConfig())
     assert whole.raw_z is not None
-    np.testing.assert_array_equal(plain.z, whole.raw_z)
+    np.testing.assert_allclose(plain.z, whole.raw_z, atol=1e-9)
     assert plain.z is not whole.raw_z
 
 
@@ -179,15 +180,15 @@ def test_apply_water_column_non_finite_z_is_missing_not_outside() -> None:
     assert out.depth_outside is not None and out.depth_outside.tolist() == [0]
 
 
-def test_z_through_a_bridged_gap_is_nan_not_interpolated() -> None:
+def test_z_through_a_bridged_gap_is_bridged_like_xy() -> None:
     session = _session_z([(0, 10), (12, 22)])
     cfg = PreprocessConfig(gap_fill=GapFillCfg(across_tracking_intervals=True))
     psess = run(session, cfg, bridge_allowed=True)
     assert psess.z is not None and psess.tracked_mask is not None
     assert psess.separator_mask is not None
     bridged = ~psess.tracked_mask & ~psess.separator_mask
     assert bridged.any()
-    assert np.isnan(psess.z[bridged]).all()
+    assert np.isfinite(psess.z[bridged]).all()
     assert np.isfinite(psess.xy[bridged]).any()
 
 
@@ -221,7 +222,7 @@ def test_fuse_refuses_native_3d_sessions() -> None:
             fuse(top, side, pair, same_video=False)
 
 
-def test_a_replaced_jump_also_blanks_z() -> None:
+def test_a_replaced_jump_also_re_fills_z() -> None:
     n = 40
     session = _session_z(None, n)
     xy = np.zeros((n, 1, 2))
@@ -233,6 +234,7 @@ def test_a_replaced_jump_also_blanks_z() -> None:
     out = run(session, config)
     assert out.jump_replaced is not None and out.jump_replaced[20, 0]
     assert out.z is not None
-    assert np.isnan(out.z[20, 0])
-    assert np.isfinite(out.z[10, 0]) and out.z[10, 0] == session.raw_z[10, 0]
+    # the glitch's own z is dropped and rebuilt from its neighbours (a line here: 120)
+    assert out.z[20, 0] == pytest.approx(120.0, abs=1e-9)
+    assert np.isfinite(out.z[10, 0]) and out.z[10, 0] == pytest.approx(110.0, abs=1e-9)
     assert session.raw_z[20, 0] == 120.0  # the session's own array is untouched
@@ -0,0 +1,193 @@
+"""The vertical axis of a native 3-D file goes through the same preprocessing as xy."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+from track2data.core.models import (
+    GapFillCfg,
+    IdSwitchCfg,
+    JumpCfg,
+    PreprocessConfig,
+    Session,
+    SmoothCfg,
+    VideoInfo,
+)
+from track2data.preprocess.pipeline import run
+
+
+def _session(xy: np.ndarray, z: np.ndarray, intervals=None) -> Session:
+    return Session(
+        velocity_threshold_px_frame=20.0,
+        session_id="s",
+        folder=Path("/tmp/s"),
+        reader="test",
+        video=VideoInfo(fps=30.0, n_frames=len(xy), width_px=0, height_px=0),
+        n_animals=1,
+        trajectory_variant="with_gaps",
+        has_stable_identities=True,
+        raw_xy=xy,
+        raw_z=z.reshape(len(z), 1),
+        has_pixel_frame=False,
+        coordinate_unit="cm",
+        tracking_intervals=intervals,
+    )
+
+
+def _cfg(*, gap=False, jump=False, smooth=None, across=False, max_gap=30) -> PreprocessConfig:
+    return PreprocessConfig(
+        gap_fill=GapFillCfg(
+            enabled=gap, max_gap_frames=max_gap, across_tracking_intervals=across
+        ),
+        jump=JumpCfg(
+            enabled=jump, method="idtracker_velocity_threshold", replacement="linear_interp"
+        ),
+        identity_switch=IdSwitchCfg(enabled=False),
+        smoothing=smooth or SmoothCfg(enabled=False),
+    )
+
+
+def _line(n: int = 60):
+    xy = np.zeros((n, 1, 2))
+    xy[:, 0, 0] = np.arange(n, dtype=float)
+    z = np.arange(n, dtype=float) * 0.5
+    return xy, z
+
+
+def _path(z: np.ndarray) -> float:
+    return float(np.nansum(np.abs(np.diff(z))))
+
+
+def test_z_is_smoothed_with_the_xy_settings() -> None:
+    rng = np.random.default_rng(0)
+    xy, _ = _line(300)
+    z = np.full(300, 5.0) + rng.normal(0.0, 0.2, 300)
+    cfg = _cfg(smooth=SmoothCfg(enabled=True, method="savgol", window=25, polyorder=2))
+
+    psess = run(_session(xy, z), cfg)
+
+    assert psess.z is not None
+    # a flat true track: smoothing must remove most of the noise path, not leave it raw
+    assert _path(psess.z[:, 0]) < 0.25 * _path(z)
+
+
+def test_z_is_unchanged_when_smoothing_and_gap_fill_are_off() -> None:
+    xy, z = _line()
+    z = z + np.random.default_rng(1).normal(0, 0.1, len(z))
+    psess = run(_session(xy, z), _cfg())
+    assert psess.z is not None
+    np.testing.assert_array_equal(psess.z[:, 0], z)
+
+
+def test_short_z_gap_is_filled_like_xy() -> None:
+    xy, z = _line()
+    xy[10:15] = np.nan
+    z[10:15] = np.nan
+    psess = run(_session(xy, z), _cfg(gap=True))
+    assert psess.z is not None
+    np.testing.assert_allclose(psess.z[10:15, 0], np.arange(10, 15) * 0.5)
+
+
+def test_z_gap_longer_than_max_stays_missing() -> None:
+    xy, z = _line()
+    xy[10:20] = np.nan
+    z[10:20] = np.nan
+    psess = run(_session(xy, z), _cfg(gap=True, max_gap=5))
+    assert psess.z is not None
+    assert np.isnan(psess.z[10:20, 0]).all()
+
+
+def test_a_z_gap_xy_does_not_have_is_not_invented_beyond_the_anchors() -> None:
+    """The leading edge has no left anchor, so it stays missing exactly as xy would."""
+    xy, z = _line()
+    z[:3] = np.nan
+    psess = run(_session(xy, z), _cfg(gap=True))
+    assert psess.z is not None
+    assert np.isnan(psess.z[:3, 0]).all()
+
+
+def test_jump_replaced_z_is_refilled_not_kept_raw() -> None:
+    xy, z = _line()
+    xy[30, 0, 0] += 500.0  # triangulation glitch in the horizontal plane
+    z[30] += 40.0  # and in the vertical one
+    cfg = _cfg(gap=True, jump=True)
+
+    psess = run(_session(xy, z), cfg)
+
+    assert psess.jump_replaced is not None and psess.jump_replaced[30, 0]
+    assert psess.z is not None
+    np.testing.assert_allclose(psess.z[30, 0], 0.5 * (z[29] + z[31]))
+
+
+def test_jump_replaced_z_stays_missing_when_gap_fill_is_off() -> None:
+    xy, z = _line()
+    xy[30, 0, 0] += 500.0
+    psess = run(_session(xy, z), _cfg(jump=True))
+    assert psess.z is not None
+    assert np.isnan(psess.z[30, 0])
+
+
+def test_z_is_bridged_across_a_tracking_interval_gap_like_xy() -> None:
+    n = 20
+    xy = np.zeros((n, 1, 2))
+    xy[:, 0, 0] = np.arange(n, dtype=float)
+    z = np.arange(n, dtype=float) + 100.0
+    session = _session(xy, z, intervals=[(0, 10), (12, 22)])
+
+    psess = run(session, _cfg(gap=True, across=True), bridge_allowed=True)
+
+    assert psess.z is not None and psess.tracked_mask is not None
+    assert psess.separator_mask is not None
+    bridged = ~psess.tracked_mask & ~psess.separator_mask
+    assert bridged.any()
+    # anchors: z=109 at video frame 9, z=110 at frame 12; video frames 10 and 11 lie on the line
+    np.testing.assert_allclose(psess.z[bridged, 0], [109 + 1 / 3, 109 + 2 / 3])
+
+
+def test_separator_rows_stay_missing_in_z() -> None:
+    xy, z = _line(22)
+    session = _session(xy, z, intervals=[(0, 10), (1000, 1012)])
+    psess = run(session, _cfg(gap=True, smooth=SmoothCfg(enabled=True)))
+    assert psess.separator_mask is not None and psess.separator_mask.any()
+    assert psess.z is not None
+    assert np.isnan(psess.z[psess.separator_mask]).all()
+
+
+def _noisy_helix(n: int = 600, sigma: float = 0.2):
+    """p7 of the 3-D review: a helix with 2 mm (0.2 cm) noise on every axis, 30 fps."""
+    rng = np.random.default_rng(3)
+    t = np.arange(n) / 30.0
+    xy = np.zeros((n, 1, 2))
+    xy[:, 0, 0] = 10 * np.cos(2 * np.pi * 0.2 * t) + rng.normal(0, sigma, n)
+    xy[:, 0, 1] = 10 * np.sin(2 * np.pi * 0.2 * t) + rng.normal(0, sigma, n)
+    true_z = 5 + 2 * np.sin(2 * np.pi * 0.1 * t)
+    return xy, true_z + rng.normal(0, sigma, n), true_z
+
+
+def test_vertical_path_falls_with_the_smoothing_window_toward_the_truth() -> None:
+    """Before: the vertical path was 129 cm at every window against a true 16 cm."""
+    xy, z, true_z = _noisy_helix()
+    paths = []
+    for window in (5, 15, 41):
+        cfg = _cfg(smooth=SmoothCfg(enabled=True, method="savgol", window=window, polyorder=2))
+        psess = run(_session(xy, z), cfg)
+        assert psess.z is not None
+        paths.append(_path(psess.z[:, 0]))
+
+    assert paths[0] > paths[1] > paths[2]
+    assert paths[2] < 0.25 * _path(z)
+    assert paths[2] < 1.5 * _path(true_z)
+
+
+def test_a_sensitivity_grid_point_changes_z() -> None:
+    from track2data.core.models import PreprocessConfig as Cfg
+    from track2data.sensitivity import GridPoint, _config_for
+
+    xy, z, _ = _noisy_helix()
+    session = _session(xy, z)
+    narrow = run(session, _config_for(Cfg(), GridPoint(smoothing_window=5, max_gap_frames=10)))
+    wide = run(session, _config_for(Cfg(), GridPoint(smoothing_window=41, max_gap_frames=10)))
+    assert narrow.z is not None and wide.z is not None
+    assert _path(wide.z[:, 0]) < _path(narrow.z[:, 0])
@@ -822,7 +822,7 @@ def import_sessions(
     # ── preprocessed-session cache ─────────────────────────────────────────
 
     #: Bump when PreprocessedSession's layout or preprocessing semantics change.
-    _CACHE_SCHEMA = 6
+    _CACHE_SCHEMA = 7
 
     def _cache_key(self, ref: SessionRef) -> tuple[Any, str] | None:
         """(store, key) for the session *ref* describes, or None when caching is
 
@@ -924,10 +924,10 @@ class PreprocessedSession:
     depth_outside_mask: np.ndarray | None = None
     # (n_rows, n_animals) absolute vertical coordinate of a native 3-D session, in the
     # session's coordinate unit, laid out on the same rows as ``xy`` (NaN on inserted rows).
-    # None for every other session. It is the file's raw coordinate: identity-switch correction,
-    # jump replacement, gap fill and smoothing change ``xy`` but never touch ``z``, so it is
-    # only valid for single-animal sources (native files are one animal) and 3-D speeds mix
-    # smoothed xy with unsmoothed z.
+    # None for every other session. It is the file's coordinate cleaned like ``xy``: blanked
+    # where a jump was replaced, then bridged, gap-filled and smoothed with the same settings
+    # (preprocess/z_axis.py). Identity-switch correction never touches it, so it is only valid
+    # for single-animal sources (native files are one animal).
     z: np.ndarray | None = None
     # (n_animals,) int: the top session's animal index of each fused animal (fusion keeps only
     # the fish in the pair's fish map, so fused position k is not top animal k). None otherwise.
 
@@ -1884,7 +1884,8 @@ class PathLength3D(Metric):
         warnings=[
             "Under-smoothed data inflates the length, exactly as for IL-1: summing step "
             "lengths sums |dx| rather than dx, so positional noise always adds length and the "
-            "inflation grows with frame rate. Depth noise adds to it as well.",
+            "inflation grows with frame rate. Depth noise adds to it as well; a native 3-D "
+            "file's z is smoothed with the same settings as x and y.",
             "No refraction or parallax correction: a fish near the front glass looks larger "
             "and sits at a different apparent depth than one at the back.",
             "A wrong tank height scales every vertical distance, and so the 3-D length, by the "
 
@@ -20,6 +20,7 @@
 from track2data.preprocess.smoothing import smooth_trajectories
 from track2data.preprocess.timeline_expand import bridge_gaps, lay_out, plan_expansion
 from track2data.preprocess.validate import validate_coverage
+from track2data.preprocess.z_axis import clean_z
 
 
 def _replaced_mask(before: np.ndarray, after: np.ndarray) -> np.ndarray:
@@ -169,6 +170,9 @@ def _checkpoint(_step: str) -> None:
     _checkpoint("smoothing")
     xy, step = smooth_trajectories(xy, config.smoothing)
     report.steps.append(step)
+    if z_rows is not None:
+        # the vertical axis follows the horizontal one through the same gap-fill and smoothing
+        z_rows = clean_z(z_rows, config.gap_fill, config.smoothing, expansion)
 
     # 5. Coverage validation
     _checkpoint("coverage validation")
 
@@ -0,0 +1,47 @@
+"""The vertical axis of a native 3-D file, put through the same cleaning steps as xy.
+
+``z`` is a single column per animal, so it reuses the one-dimensional workers of the xy steps
+(``gap_fill._fill_series``, ``smoothing._smooth_series_*``, ``timeline_expand.bridge_gaps``) rather
+than the ``(n_frames, n_animals, 2)`` wrappers. The same settings govern it, so a 3-D position is
+cleaned as one object: smoothing the horizontal plane while leaving the vertical raw made the
+vertical share of a 3-D path length several times too large and no setting could reduce it.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from track2data.core.models import GapFillCfg, SmoothCfg
+from track2data.preprocess.gap_fill import _fill_series
+from track2data.preprocess.smoothing import _smooth_series_moving_avg, _smooth_series_savgol
+from track2data.preprocess.timeline_expand import Expansion, bridge_gaps
+
+
+def clean_z(
+    z: np.ndarray,
+    gap_cfg: GapFillCfg,
+    smooth_cfg: SmoothCfg,
+    expansion: Expansion | None,
+) -> np.ndarray:
+    """``z`` ``(n_rows, n_animals)`` bridged, gap-filled and smoothed like xy; input untouched.
+
+    The caller blanks the rows where xy was jump-replaced first, so they are re-filled from their
+    neighbours instead of keeping a raw vertical value beside a corrected horizontal one.
+    """
+    out = z.copy()
+    if expansion is not None and expansion.bridged_mask.any():
+        out, _ = bridge_gaps(out[:, :, None], expansion)
+        out = out[:, :, 0]
+    if gap_cfg.enabled:
+        protected = None if expansion is None else ~expansion.tracked_mask
+        for k in range(out.shape[1]):
+            out[:, k], _ = _fill_series(out[:, k], gap_cfg.max_gap_frames, protected)
+    if smooth_cfg.enabled and smooth_cfg.method != "none":
+        for k in range(out.shape[1]):
+            if smooth_cfg.method == "savgol":
+                out[:, k] = _smooth_series_savgol(
+                    out[:, k], smooth_cfg.window, smooth_cfg.polyorder
+                )
+            else:
+                out[:, k] = _smooth_series_moving_avg(out[:, k], smooth_cfg.window)
+    return out