Python client¶
The package ships a high-level client, Mef3Client, wrapping the gRPC API. All
data access is oriented in channels and time: open a file, inspect its
metadata, then read any channels over any [start_uutc, end_uutc) window. See
the API reference for the full method signatures.
Connecting¶
from mef3io_server.client import Mef3Client
client = Mef3Client("localhost:50051")
Opening a file and reading metadata¶
open_file returns the file's metadata as a dict. When the server runs in
Docker, pass the absolute path as it exists on the host — the server maps it
under /host_root automatically (see Docker deployment).
info = client.open_file("/path/to/file.mefd")
info["channel_names"] # list[str]
info["channel_sampling_rates"] # per-channel fs, parallel to channel_names
info["channel_start_uutc"] # per-channel start times (uUTC)
info["channel_end_uutc"] # per-channel end times (uUTC)
info["start_uutc"] # global min start
info["end_uutc"] # global max end
info["duration_s"] # recording span in seconds
get_file_info returns the same metadata for an already-open file without
re-opening it.
Reading a signal range¶
get_signal_range reads any channels over any [start_uutc, end_uutc) window.
Times are microseconds (uUTC); the returned array is float32.
t0 = info["start_uutc"]
res = client.get_signal_range(
"/path/to/file.mefd",
channels=["Ch1", "Ch2"], # None reads all channels
start_uutc=t0,
end_uutc=t0 + 10_000_000, # +10 s
)
res["array"] # np.ndarray, shape (n_channels, n_samples), float32
res["channel_names"] # channel order of the rows
res["fs"] # sampling rate
The requested channels must share a sampling rate; reads past end-of-file are NaN-padded. Repeated or overlapping requests are served from the tile cache, and neighboring windows are prefetched in the background for smooth paging.
Serving at a lower rate (cache_fs)¶
For viewers, a session can ask the server to serve, cache and prefetch its reads at a lower rate:
info = client.open_file("/path/to/file.mefd", cache_fs=128)
info["channel_served_sampling_rates"] # the rate each channel is served at
data = client.get_signal_range(path, channels, t0, t1) # data["fs"] == 128
- Order-preserving min-max. Each pair of output samples covers
2 / cache_fsseconds of the original and holds that stretch's minimum and maximum, in the order they occurred. A spike is never lost (it is the minimum or maximum of its stretch), and the trace keeps its shape. Every value is a real sample. - Cached at that rate. At 4096 Hz -> 128 Hz the cache holds 32 times more time in the same memory, and prefetch works the same way.
- The server never upsamples. If a channel is recorded below
cache_fs, the open fails (file_openedis False, anderror_messagenames the channels). Passallow_mixed_rates=Trueto serve such channels at their own rate instead;channel_served_sampling_ratesthen tells you which. - The setting belongs to this client's session: another tool reading the same
file at another rate, or at the original rate, is unaffected. Opening again
without
cache_fsgoes back to the original rate. - If the session expires while the file stays open (another client still uses it), the next read restores it with the same rate.
- A refused open (
file_openedis False because of the rate check) leaves an existing session of this client as it was; it does not close the file. cache_fsneeds a client id, whichMef3Clientalways sends. A server older than this feature makesopen_file(..., cache_fs=...)raise instead of silently serving the original rate.- Buckets are cut per cache tile. When the original rate is not a whole
multiple of
cache_fs, a bucket at a tile edge can be one original sample shorter or longer than its neighbours; no sample is lost or counted twice.
Exactly as many points as the view has pixels (n_points)¶
data = client.get_signal_range(path, channels, t0, t1, n_points=584)
data["array"].shape # (len(channels), 584)
data["fs"] # 584 / window length in seconds
- MinMaxLTTB. The window is cut into
n_pointsbuckets. Each point is a real sample, its bucket's minimum or maximum, chosen to keep the line's shape (Largest-Triangle-Three-Buckets). One point per bucket means one of a bucket's two extremes is left out, but each channel's overall maximum and minimum in the window are always among the points, so the amplitude is never understated (if both fall in one bucket, the larger excursion is kept). - The requested channels must be served at one rate, as for any read; with
allow_mixed_rates, request channels of different rates separately. - The cheapest source with detail to spare. If the session has a
cache_fsand it holds at least2 * n_pointssamples in the window, the points come from the cached data with no decoding. When you zoom in further, they come from the original rate. - Never upsampled. When the window holds
n_pointssamples or fewer at the original rate, they are returned unchanged. - Without
n_points, reads come back at the session's rate, as before.
Cleaning up¶
Sessions¶
Each Mef3Client sends a client id with every call (a random one, or
Mef3Client(address, client_id="...")). The server keeps one session per
client and file:
- opening the same file again from the same client reuses its session, so a tool that re-opens on every page view does not pile up sessions;
- two clients (two tools, two users) have separate sessions on the same file, while sharing the server's open reader and its decoded tiles;
- a client can read a file another client opened, so tools can share a file one of them opened;
- a session idle longer than
SESSION_TTL_S(30 min by default) is closed.
The id is a name tag, not authentication. A web app serving several users can
pass one id per user. Create one Mef3Client per tool or user and keep it: each new
client object has a new random id, so creating one per request leaves a
session per request until they expire.
Closing a file ends this client's session (file_opened in the reply says
whether the file is still open for other clients). The reader is released, and the
file's tiles purged from the shared cache, when no other session uses the file.
Shut the client down when you are done:
client.close_file("/path/to/file.mefd")
client.shutdown()