EchoXFlow conversion by swpenninga · Pull Request #424 · tue-bmd/zea

swpenninga · 2026-06-10T14:24:34Z

Merging into openh-rf, not main, to use the new dataformat. (but this is not channel data, its B-mode)
Created a huggingface repository v0.1.0 here. It is public which is allowed under cc by nc sa 4.0.
The conversion script test had to break the format of the other scripts, since the echoxflow module/package was required, so i broke out of the subprocess CLI run as a workaround.

This is not the entire dataset, it contains some filters. To keep things managable (and high quality), we copy only the 2D (single plane) B-modes:

with the following filters:
>30fps, >10frames in the sequence
this avoids some low quality single frames or noise frames that are used for probe positioning for example.

All the metadata that comes with these files is transferred to zea format.

Some interesting statistics about the 1291 different data shapes with these filters:

H × W	Count	%
718 × 242	1,605	11.8%
723 × 242	721	5.3%
728 × 242	678	5.0%
737 × 242	556	4.1%
727 × 242	485	3.6%
732 × 242	471	3.5%
735 × 242	420	3.1%
723 × 274	276	2.0%
718 × 274	234	1.7%
728 × 274	230	1.7%

W	Count	%
242	5,420	39.8%
274	1,679	12.3%
210	1,123	8.2%
198	1,042	7.6%
226	801	5.9%

coderabbitai · 2026-06-10T14:24:45Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 7a34b2f8-64a3-430f-84fd-7d38904db478

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch echoxflow-convert

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

codecov · 2026-06-10T16:09:54Z

Codecov Report

❌ Patch coverage is 83.00000% with 34 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
zea/data/convert/echoxflow.py	70.52%	19 Missing and 9 partials ⚠️
tests/data/test_conversion_scripts.py	94.17%	5 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

…to echoxflow-convert

swpenninga · 2026-06-15T12:21:01Z

fixed now, i will rerun conversion + upload to use the new timestamps

tristan-deep · 2026-06-15T14:45:11Z

Testing right now. @swpenninga could you upload the dataset on the HF branch "v0.1.0" instead of "0.1.0"? That is how it is done for the other datasets too now. After you can remove the "0.1.0". Also could you update the embedded zea version to "0.1.0" (by updating the toml and installing again). I see it is now 0.0.11 which contradicts the HF branch version.

tristan-deep · 2026-06-15T14:54:19Z

@swpenninga I see the images are now saved as (z, x, 1) ? I think (z, x) is also allowed. Have to check with @OisinNolan if that also makes sense with coordinates that are stored alongside, seems that always has to be [x, y, z] in the last axis.

swpenninga · 2026-06-15T14:54:20Z

Testing right now. @swpenninga could you upload the dataset on the HF branch "v0.1.0" instead of "0.1.0"? That is how it is done for the other datasets too now. After you can remove the "0.1.0". Also could you update the embedded zea version to "0.1.0" (by updating the toml and installing again). I see it is now 0.0.11 which contradicts the HF branch version.

Running that right now!

tristan-deep · 2026-06-15T14:58:06Z

Testing right now. @swpenninga could you upload the dataset on the HF branch "v0.1.0" instead of "0.1.0"? That is how it is done for the other datasets too now. After you can remove the "0.1.0". Also could you update the embedded zea version to "0.1.0" (by updating the toml and installing again). I see it is now 0.0.11 which contradicts the HF branch version.

Running that right now!

Nice! Also wouldn't be opposed to putting everything in a dataset folder, so it is easier for people to see the readme / license etc. auxiliary files. Don't need to rerun, can use hugging face checkout to rearrange files maybe as quick fix? Sorry for last minute comment....

tristan-deep · 2026-06-15T15:50:25Z

Just used this snippet to test the dataset, added some loose comments above but overall seems working. Really nice addition! This is quite a cool dataset.

import zea

with zea.Dataset("hf://zeahub/echoxflow/", revision="0.1.0", lazy=True) as ds:
    f = ds[20]
    sequence = f.data.image.values[:].astype(np.float32)  # (n_frames, z, x, y)
    sequence_time = np.asarray(f.metadata.bmode_timestamps.timestamps[:])
    coordinates = np.asarray(f.data.image.coordinates[:])  # (H, W, 3): [x, y, z] in metres
    ecg = np.asarray(f.metadata.ecg.samples[:])
    ecg_time = np.asarray(f.metadata.ecg.timestamps[:])

    sequence = sequence[..., 0]  # (n_frames, z, x)

And full example below:

Full snippet

import numpy as np
from PIL import Image, ImageDraw

import zea
from zea.display import scan_convert
from zea.io_lib import save_video

with zea.Dataset("hf://zeahub/echoxflow/", revision="0.1.0", lazy=True) as ds:
    f = ds[20]
    sequence = f.data.image.values[:].astype(np.float32)  # (n_frames, z, x, y)
    sequence_time = np.asarray(f.metadata.bmode_timestamps.timestamps[:])
    coordinates = np.asarray(f.data.image.coordinates[:])  # (H, W, 3): [x, y, z] in metres
    ecg = np.asarray(f.metadata.ecg.samples[:])
    ecg_time = np.asarray(f.metadata.ecg.timestamps[:])

    sequence = sequence[..., 0]  # (n_frames, z, x)

    # FPS from actual frame timestamps
    fps = float(1.0 / np.mean(np.diff(sequence_time)))

    # Derive polar ranges from stored per-pixel Cartesian coordinates.
    # The first row sits at the apex (rho=0), so all coords are [0,0,0] there.
    # Use the last (deepest) row to get a valid theta range.
    coords = coordinates[0] if coordinates.ndim == 4 else coordinates  # (z, x, 3)
    x, z = coords[..., 0], coords[..., 2]
    W_mid = coords.shape[1] // 2
    rho_range = (
        float(np.sqrt(x[0, W_mid] ** 2 + z[0, W_mid] ** 2)),
        float(np.sqrt(x[-1, W_mid] ** 2 + z[-1, W_mid] ** 2)),
    )
    theta_range = (
        float(np.arctan2(x[-1, 0], z[-1, 0])),
        float(np.arctan2(x[-1, -1], z[-1, -1])),
    )

    # Scan convert: polar → Cartesian for the full sequence in one pass
    sequence_sc, _ = scan_convert(
        sequence,
        rho_range=rho_range,
        theta_range=theta_range,
        with_batch_dim=True,
    )
    sequence_sc = np.clip(np.asarray(sequence_sc), 0, 255).astype(np.uint8)  # (N, H_sc, W_sc)

    # --- ECG overlay strip ---
    N, H_sc, W_sc = sequence_sc.shape
    strip_h = 80
    t_total = float(ecg_time[-1])

    # Resample ECG onto the frame width (handles irregular ECG timestamps)
    t_uniform = np.linspace(0.0, t_total, W_sc)
    ecg_resampled = np.interp(t_uniform, ecg_time, ecg)
    ecg_min, ecg_max = ecg_resampled.min(), ecg_resampled.max()
    ecg_norm = (ecg_resampled - ecg_min) / (ecg_max - ecg_min + 1e-8)

    # Pre-render the ECG waveform as a PIL strip (red on black)
    strip_base = Image.new("RGB", (W_sc, strip_h), (0, 0, 0))
    draw = ImageDraw.Draw(strip_base)
    pts = [(j, strip_h - 1 - int(ecg_norm[j] * (strip_h - 1))) for j in range(W_sc)]
    draw.line(pts, fill=(220, 30, 30), width=2)
    strip_base = np.array(strip_base)

    # Composite each frame: scan-converted B-mode (→ RGB) + ECG strip with time cursor
    frames = []
    for i in range(N):
        frame_rgb = np.repeat(sequence_sc[i, :, :, np.newaxis], 3, axis=-1)

        strip = strip_base.copy()
        x_cursor = int(sequence_time[i] / t_total * (W_sc - 1))
        strip[:, max(0, x_cursor - 1) : x_cursor + 2] = (220, 30, 30)  # red cursor

        frames.append(np.concatenate([frame_rgb, strip], axis=0))

    save_video(np.array(frames), "echoxflow.gif", fps=fps)

swpenninga · 2026-06-15T22:37:33Z

branch was changed to v0.1.0 now, not sure how to delete the old one

OisinNolan · 2026-06-16T07:06:07Z

@swpenninga I see the images are now saved as (z, x, 1) ? I think (z, x) is also allowed. Have to check with @OisinNolan if that also makes sense with coordinates that are stored alongside, seems that always has to be [x, y, z] in the last axis.

It is allowed by the spec to have a channel dim in your images, which can be 1 (it is an empty dim, but the spec allows it.) The coordinates also look correct -- they just need to match the spatial dims
cc @tristan-deep

tristan-deep · 2026-06-16T07:15:33Z

@swpenninga I see the images are now saved as (z, x, 1) ? I think (z, x) is also allowed. Have to check with @OisinNolan if that also makes sense with coordinates that are stored alongside, seems that always has to be [x, y, z] in the last axis.

It is allowed by the spec to have a channel dim in your images, which can be 1 (it is an empty dim, but the spec allows it.) The coordinates also look correct -- they just need to match the spatial dims cc @tristan-deep

Right, but would (z, x) simply also be allowed? Since the data is 2D. Or better to be consistent and always do (z, x, y) even if y=1? Since (z, x) seems allowed from the docs I thought it would be a better option for this dataset.

OisinNolan

looks good @swpenninga , nice work! This was a cool dataset to test the metadata spec with -- left one comment on that but otherwise I think it's good to go

OisinNolan · 2026-06-16T07:32:53Z

+            metadata["bmode_timestamps"] = {
+                "samples": ts,
+                "timestamps": ts - ts[0],
+                "start_time_offset": np.float32(ts[0]),


I found this part a little confusing -- we're storing here a signal whose values are absolute timestamps and whose timestamps are relative timestamps

I think this happens because (i) we want to record the timestamps of the B-mode frames, but (ii) we require a custom signal to have samples

I think there are two options here:
(i) We add an optional timestamp array to Map (non-breaking), where it's simply a 1D float array whose length needs to match the first dim of the Map.values (preferred)
(ii) We allow custom signals to be just Signal instead of SignalND

what do you think?

I think option one would be perfect. Als found the current way of saving confusing when working on my example snippet.

OisinNolan · 2026-06-16T07:38:35Z

@swpenninga I see the images are now saved as (z, x, 1) ? I think (z, x) is also allowed. Have to check with @OisinNolan if that also makes sense with coordinates that are stored alongside, seems that always has to be [x, y, z] in the last axis.

It is allowed by the spec to have a channel dim in your images, which can be 1 (it is an empty dim, but the spec allows it.) The coordinates also look correct -- they just need to match the spatial dims cc @tristan-deep

Right, but would (z, x) simply also be allowed? Since the data is 2D. Or better to be consistent and always do (z, x, y) even if y=1? Since (z, x) seems allowed from the docs I thought it would be a better option for this dataset.

@tristan-deep yeah indeed -- (z, x) is also allowed and maybe preferred here, unless there's a good reason to keep the channel dim (e.g. maybe it helps distinguish between different types of image in the dataset or something). What do you think @swpenninga ?

tristan-deep · 2026-06-16T08:36:05Z

Testing right now. @swpenninga could you upload the dataset on the HF branch "v0.1.0" instead of "0.1.0"? That is how it is done for the other datasets too now. After you can remove the "0.1.0". Also could you update the embedded zea version to "0.1.0" (by updating the toml and installing again). I see it is now 0.0.11 which contradicts the HF branch version.

Basically just git, but using pointers so you don't have to download the entire dataset (using GIT_LFS_SKIP_SMUDGE=1).

# clone repo, but using pointers only
export GIT_LFS_SKIP_SMUDGE=1

git clone https://huggingface.co/datasets/zeahub/echoxflow
cd echoxflow
# see branches
git branch -a
# delete the local branch 
git branch --delete 0.1.0
# delete remote branch
git push origin --delete 0.1.0
# check
git log --oneline

Make sure your HF_TOKEN is set to write as well, but probably already is given that is also necessary for the Python API.

swpenninga · 2026-06-17T12:34:23Z

@OisinNolan @tristan-deep i added the timestamp to the Map, and i removed the trailing 1 dim to get (z, x) in the last commit. Let me know if I can start (hopefully the last) conversion and upload to hf!

tristan-deep · 2026-06-17T14:00:49Z

@OisinNolan @tristan-deep i added the timestamp to the Map, and i removed the trailing 1 dim to get (z, x) in the last commit. Let me know if I can start (hopefully the last) conversion and upload to hf!

For me all good! Changes look good. Will test after conversion again! (or if you already have a sample available)

OisinNolan

Conversion lgtm! Just one remaining issue regarding the update to the spec

OisinNolan · 2026-06-17T14:08:57Z

            the shape is ``(*values.shape[:-1], 3)``.  The last axis holds ``[x, y, z]``.
            The leading ``n_frames`` axis may be omitted to broadcast one coordinate grid
            across all frames.
+        timestamps: Optional per-frame acquisition timestamps in seconds, shape ``(n_frames,)``.


nice addition!
I'm just thinking -- maybe the definition here should match that of timestamps on the Signal and ProbePose spec -- there we generally define them as relative to the first transmit event of the acquisition. This would mean we could more easily compare timestamps across these different sources.

We would also then need a start_time_offset like in the other cases, with some validation that it's also set if we specify timestamps, and that timestamps are >0

echoxflow conversion

755a6d4

swpenninga added enhancement New feature or request tests Tests data format Related to the zea data format saving and loading labels Jun 10, 2026

Merge branch 'openh-rf' into echoxflow-convert

e09ebcf

swpenninga and others added 5 commits June 10, 2026 21:14

echoxflow install fix

faf45bc

Merge branch 'echoxflow-convert' of https://github.com/tue-bmd/zea in…

71caa6a

…to echoxflow-convert

Allow upload after conversion

f4cc26e

Merge branch 'openh-rf' into echoxflow-convert

31e53a4

Merge branch 'openh-rf' into echoxflow-convert

3617202

swpenninga marked this pull request as ready for review June 11, 2026 08:52

swpenninga requested review from a team and OisinNolan and removed request for a team June 11, 2026 08:52

Merge branch 'openh-rf' into echoxflow-convert

bca5b62

OisinNolan reviewed Jun 11, 2026

View reviewed changes

Comment thread zea/data/convert/echoxflow.py Outdated

tristan-deep and others added 3 commits June 12, 2026 07:58

Merge branch 'openh-rf' into echoxflow-convert

f6ae781

Merge branch 'openh-rf' into echoxflow-convert

f8e4389

timestamping instead of implied sampling rate

890faa5

swpenninga requested review from OisinNolan and tristan-deep June 15, 2026 12:20

swpenninga and others added 3 commits June 15, 2026 14:22

Merge branch 'openh-rf' into echoxflow-convert

54c7ed2

Merge branch 'openh-rf' into echoxflow-convert

1ff334d

Merge branch 'openh-rf' into echoxflow-convert

84555d6

filename not wrapped in log.yellow

f1930b1

tristan-deep and others added 2 commits June 15, 2026 23:24

Merge branch 'openh-rf' into echoxflow-convert

69ff628

Merge branch 'openh-rf' into echoxflow-convert

1198f42

OisinNolan reviewed Jun 16, 2026

View reviewed changes

Merge branch 'openh-rf' into echoxflow-convert

3c8f9f3

tristan-deep added this to the v0.1.0 (OpenH-RF) milestone Jun 17, 2026

add timestamp to spec and remove trailing 1 dim

916059c

Merge branch 'openh-rf' into echoxflow-convert

5ce7e32

OisinNolan requested changes Jun 17, 2026

View reviewed changes

Conversation

swpenninga commented Jun 10, 2026 • edited by tristan-deep Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

codecov Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

swpenninga commented Jun 15, 2026

Uh oh!

tristan-deep commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tristan-deep commented Jun 15, 2026

Uh oh!

swpenninga commented Jun 15, 2026

Uh oh!

tristan-deep commented Jun 15, 2026

Uh oh!

tristan-deep commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

swpenninga commented Jun 15, 2026

Uh oh!

OisinNolan commented Jun 16, 2026

Uh oh!

tristan-deep commented Jun 16, 2026

Uh oh!

OisinNolan left a comment

Choose a reason for hiding this comment

Uh oh!

OisinNolan Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

tristan-deep Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

OisinNolan commented Jun 16, 2026

Uh oh!

tristan-deep commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

swpenninga commented Jun 17, 2026

Uh oh!

tristan-deep commented Jun 17, 2026

Uh oh!

OisinNolan left a comment

Choose a reason for hiding this comment

Uh oh!

OisinNolan Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

OisinNolan Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

swpenninga commented Jun 10, 2026 •

edited by tristan-deep

Loading

coderabbitai Bot commented Jun 10, 2026 •

edited

Loading

codecov Bot commented Jun 10, 2026 •

edited

Loading

tristan-deep commented Jun 15, 2026 •

edited

Loading

tristan-deep commented Jun 15, 2026 •

edited

Loading

tristan-deep commented Jun 16, 2026 •

edited

Loading