diff --git a/csaxs_bec/bec_ipython_client/plugins/omny/AI_docs/OPEN_ISSUES.md b/csaxs_bec/bec_ipython_client/plugins/omny/AI_docs/OPEN_ISSUES.md index 971f1d3f..34851dd5 100644 --- a/csaxs_bec/bec_ipython_client/plugins/omny/AI_docs/OPEN_ISSUES.md +++ b/csaxs_bec/bec_ipython_client/plugins/omny/AI_docs/OPEN_ISSUES.md @@ -30,7 +30,10 @@ as a wear limit). OMNY) — `OMNY` now has a real job queue, `at_each_angle_hook` registration, `tomo_scan_resume()`, and scan progress visible outside the CLI session (previously a plain in-memory dict). See "Tomo- queue backend ported to OMNY" below. Phase 2 (the widget itself) is a separate follow-up, not yet -started — not live-tested against a running session yet either; that's next, once Mirko pulls. +started. Live-tested by Mirko against his own session (not a sim harness), which surfaced and +fixed several more real bugs — see "scilog writes hung / migrated to bec.messaging.scilog", +"tomo_scan() rejected TomoQueueMixin's interactive= kwarg", "stale ~/Data10/ paths crashed on a +fresh session", and "tomo_parameters() now warns about too few Fermat scan points" below. **Still open / deferred** (unchanged from before, not touched this pass): - `x_ray_eye_align.py` is still LamNI-derived, unadapted code beyond the two call-site renames @@ -40,6 +43,10 @@ started — not live-tested against a running session yet either; that's next, o dewar/temperature methods, sample storage bookkeeping, and `omny_alignment_mixin.py`/ `omny_optics_mixin.py` beyond what scans exercise — see "Checklist" section below. - The `TomoParamsWidget`/`OMNY_TomoParams` GUI widget itself (Phase 2 of the tomo-queue port). +- `omny_alignment_mixin.py`/`x_ray_eye_align.py` still reference the old `~/Data10/specES1/internal/` + path for alignment-offset data (unlike the tomo-scan-path fixes below, these already tolerate a + missing path gracefully — confirmed live, no crash, just "No data available" -- so left alone for + now, but worth the same `~/data/raw/` treatment eventually for consistency). ## Standing question: OMNY should follow flOMNI, not LamNI @@ -372,6 +379,60 @@ the local bec-server may be in active use by Mirko's own parallel session; a ful numbers) -- next step is Mirko pulling and testing live himself, same pattern as this whole engagement. +## Live-testing findings after the Phase 1 port (fixed) + +Mirko live-tested Phase 1 against his own session (not a sim harness) and found four more real +bugs, all fixed in a follow-up pass: + +**scilog writes hung indefinitely.** `write_to_scilog()`/`write_pdf_report()` used the old +`bec.logbook`/`client.logbook.send_logbook_message()` API, which has no "is scilog even +configured" check -- on a session without scilog credentials, `send()` blocks forever instead of +failing fast. Confirmed live: a real `tomo_scan()` hung for 29+ minutes inside +`_write_subtomo_to_scilog()`. Per Mirko's direction ("Scilog Messaging should check the account. +In flomni we are doing this I believe"): flomni's actual mechanism turned out to be +`bec.messaging.scilog._enabled` (not literally an account check, but the same effect -- gates the +send behind whether scilog is actually configured/reachable). Migrated both OMNY call sites onto +the same `bec.messaging.scilog` API, matching flomni's `_scilog_write()`/`write_pdf_report()` +exactly. 3 new unit tests lock in the `_enabled` gate. + +**`tomo_scan()` didn't accept `interactive=`.** `TomoQueueMixin.tomo_queue_execute()` +unconditionally calls `self.tomo_scan(interactive=False)` for unattended queued runs (the same +call convention flomni/lamni already support) -- `OMNY.tomo_scan()`'s signature never had this +parameter at all, so every `tomo_queue_execute()` run failed immediately with `TypeError: got an +unexpected keyword argument 'interactive'`. Fixed by adding `interactive: bool = True`, accepted +but currently unused -- matching flomni's own docstring reasoning exactly ("FlOMNI has no +fine-alignment gate"; OMNY doesn't either). + +**Stale `~/Data10/specES1/` paths crashed on a fresh session.** Confirmed live (`FileNotFoundError` +on Mirko's Mac): `_write_tomo_scan_number()` wrote to +`~/Data10/specES1/dat-files/tomography_scannumbers.txt`, a layout that doesn't exist in the current +deployment at all -- flomni's own equivalent method already uses `~/data/raw/logs/`. Same fix +applied to `write_pdf_report()`'s PDF target (`~/Data10/documentation/` -> +`~/data/raw/documentation/`) and `tomo_reconstruct()`'s default `base_path` (`~/Data10/specES1` -> +`~/data/raw`), all three of which shared the identical stale root. Unlike flomni's own +`_write_tomo_scan_number()`/`write_pdf_report()` (which assume the target directory already +exists, and would hit this same crash on a machine where it doesn't), OMNY's versions now +explicitly `os.makedirs(..., exist_ok=True)` first -- a small hardening beyond a pure mirror, +directly motivated by this exact crash. + +**`tomo_parameters()` now warns about too few Fermat scan points.** `OmnyFermatScan.prepare_scan()` +already aborted (`ScanAbortion`) when the fovx/fovy/step combination yields fewer than +`MIN_POSITIONS` (20) points -- that abort was intentional, but nothing warned ahead of time; the +scan would just silently fail once actually run. Direct port of `Flomni.tomo_parameters()`'s +identical warning line, added right after "Stitching overlap" in the printout: "Estimated Fermat +scan points per projection: N (WARNING: below the minimum of 20 -- the scan will abort when run)". +Needed a small supporting refactor: `OmnyFermatScan.get_omny_fermat_spiral_pos()` was an instance +method reading `self.cenx`/`self.ceny`/`self.zshift` (unlike flomni's already-`@staticmethod` +version), so it couldn't be called from `tomo_parameters()` without constructing a full scan +instance -- converted to a `@staticmethod` taking `cenx`/`ceny`/`zshift` as explicit keyword args +(default `0.0`, behavior-preserving), matching flomni's signature exactly. Also promoted the +hardcoded `20` in `prepare_scan()`'s abort check to a `MIN_POSITIONS = 20` class constant (mirrors +`FlomniFermatScan.MIN_POSITIONS`), so the CLI warning and the scan server's actual enforcement can +never drift out of sync. 13 new tests across `test_omny_fermat_scan.py` (scan-level: +`MIN_POSITIONS` value, static-method callability, cenx/ceny/zshift not affecting the count, +`prepare_scan()` still aborts) and `test_omny_tomo_angles.py` (CLI-level: warning appears/doesn't +appear). + ## Environment note (not code, but will bite again if forgotten) Both `csaxs_bec` and `bec_widgets` were pip-installed editable pointing at pre-repo- diff --git a/csaxs_bec/bec_ipython_client/plugins/omny/omny.py b/csaxs_bec/bec_ipython_client/plugins/omny/omny.py index 231194a4..4653fc98 100644 --- a/csaxs_bec/bec_ipython_client/plugins/omny/omny.py +++ b/csaxs_bec/bec_ipython_client/plugins/omny/omny.py @@ -1265,8 +1265,18 @@ class OMNY( for scan_nr in range(start_scan_number, end_scan_number): self._write_tomo_scan_number(scan_nr, angle, subtomo_number) - def tomo_scan(self, subtomo_start=1, start_angle=None, projection_number=None): - """start a tomo scan""" + def tomo_scan( + self, subtomo_start=1, start_angle=None, projection_number=None, interactive: bool = True + ): + """start a tomo scan + + Args: + interactive: accepted for signature compatibility with + TomoQueueMixin.tomo_queue_execute(), which always calls + self.tomo_scan(interactive=False) for unattended queued runs + (matching flomni's/lamni's call convention) -- unused here, + OMNY has no fine-alignment gate. + """ self.omnygui_show_progress() bec = builtins.__dict__.get("bec") @@ -1578,7 +1588,7 @@ class OMNY( return angle, subtomo_number - def tomo_reconstruct(self, base_path="~/Data10/specES1"): + def tomo_reconstruct(self, base_path="~/data/raw"): """write the tomo reconstruct file for the reconstruction queue""" bec = builtins.__dict__.get("bec") base_path = os.path.expanduser(base_path) @@ -1596,9 +1606,16 @@ class OMNY( queue_file.write("p.check_nextscan_started 1\n") def _write_tomo_scan_number(self, scan_number: int, angle: float, subtomo_number: int) -> None: - tomo_scan_numbers_file = os.path.expanduser( - "~/Data10/specES1/dat-files/tomography_scannumbers.txt" - ) + # ~/data/raw/logs/ matches flomni's own _write_tomo_scan_number() -- + # the old ~/Data10/specES1/dat-files/ layout doesn't exist in the + # current deployment (confirmed live: FileNotFoundError on a fresh + # session). Unlike flomni's version, explicitly create the + # directory here rather than assuming something else already has -- + # flomni's own identical open("a+") call has the same latent + # assumption, just usually gets away with it because the directory + # already exists on deployed systems. + tomo_scan_numbers_file = os.path.expanduser("~/data/raw/logs/tomography_scannumbers.txt") + os.makedirs(os.path.dirname(tomo_scan_numbers_file), exist_ok=True) with open(tomo_scan_numbers_file, "a+") as out_file: # pylint: disable=undefined-variable out_file.write( @@ -1672,6 +1689,39 @@ class OMNY( account = os.getenv("USER") or "" return bool(account) and account in _SUPERUSER_ACCOUNTS + def _expected_fermat_position_count(self) -> int: + """Estimate the number of Fermat scan points the current + fovx/fovy/tomo_shellstep settings would produce, so a + too-few-points configuration (which the scan server would only + catch by aborting with ScanAbortion once the scan actually starts) + can be caught here instead, while just looking at tomo_parameters(). + Direct port of Flomni._expected_fermat_position_count(). + + cenx/ceny/zshift are deliberately left at their defaults: they only + shift the final position, applied after the FOV keep-or-discard + check, so they can never affect the resulting count. + """ + from csaxs_bec.scans.omny_fermat_scan import OmnyFermatScan + + positions = OmnyFermatScan.get_omny_fermat_spiral_pos( + -abs(self.fovx / 2), + abs(self.fovx / 2), + -abs(self.fovy / 2), + abs(self.fovy / 2), + step=self.tomo_shellstep, + spiral_type=0, + center=False, + ) + return len(positions) + + @staticmethod + def _fermat_min_positions() -> int: + """OmnyFermatScan's own minimum-position threshold -- see + _expected_fermat_position_count().""" + from csaxs_bec.scans.omny_fermat_scan import OmnyFermatScan + + return OmnyFermatScan.MIN_POSITIONS + def tomo_parameters(self): """print and update the tomo parameters""" print("Current settings:") @@ -1680,6 +1730,16 @@ class OMNY( print(f"FOV (200/100) = {self.fovx}, {self.fovy}") print(f"Stitching number x,y = {self.stitch_x}, {self.stitch_y}") print(f"Stitching overlap = {self.tomo_stitch_overlap}") + expected_positions = self._expected_fermat_position_count() + min_positions = self._fermat_min_positions() + if expected_positions < min_positions: + print( + f"Estimated Fermat scan points per projection: {expected_positions} " + f"(WARNING: below the minimum of {min_positions} -- the scan will abort" + " when run)" + ) + else: + print(f"Estimated Fermat scan points per projection: {expected_positions}") print(f"Reconstruction queue name = {self.ptycho_reconstruct_foldername}") print(f" _manual_shift_y = {self.manual_shift_y}") print("") @@ -1896,7 +1956,14 @@ class OMNY( "Add current temperature and pressure status", ] content = "".join(content) - user_target = os.path.expanduser(f"~/Data10/documentation/tomo_scan_ID_{self.tomo_id}.pdf") + # ~/data/raw/documentation/ matches flomni's/lamni's own + # write_pdf_report() target -- the old ~/Data10/documentation/ + # layout doesn't exist in the current deployment. PDFWriter doesn't + # create its own parent directory, so do it explicitly here. + user_target = os.path.expanduser( + f"~/data/raw/documentation/tomo_scan_ID_{self.tomo_id}.pdf" + ) + os.makedirs(os.path.dirname(user_target), exist_ok=True) with PDFWriter(user_target) as file: file.write(header) file.write(content) diff --git a/csaxs_bec/scans/omny_fermat_scan.py b/csaxs_bec/scans/omny_fermat_scan.py index 11f84007..c5a92e19 100644 --- a/csaxs_bec/scans/omny_fermat_scan.py +++ b/csaxs_bec/scans/omny_fermat_scan.py @@ -46,6 +46,7 @@ class OmnyFermatScan(ScanBase): # It must be a valid Python identifier, that is, it can only contain letters, numbers, and underscores, and must not start with a number. scan_name = "omny_fermat_scan" + MIN_POSITIONS = 20 # Minimum number of positions required for a valid scan MAX_CORRIDOR_SIZE = 3 # Corridor size is capped at this value (in um) for stability gui_config = { @@ -150,9 +151,10 @@ class OmnyFermatScan(ScanBase): center=False, ) - if len(positions) < 20: + if len(positions) < self.MIN_POSITIONS: raise ScanAbortion( - f"The number of positions must exceed 20. Currently: {len(positions)}." + f"The number of positions must exceed {self.MIN_POSITIONS}. Currently:" + f" {len(positions)}." ) corridor_size = self.corridor_size @@ -285,8 +287,8 @@ class OmnyFermatScan(ScanBase): ) return val + @staticmethod def get_omny_fermat_spiral_pos( - self, m1_start: float, m1_stop: float, m2_start: float, @@ -294,6 +296,9 @@ class OmnyFermatScan(ScanBase): step: float = 1, spiral_type: int = 0, center: bool = False, + cenx: float = 0.0, + ceny: float = 0.0, + zshift: float = 0.0, ): """ Calculate positions for a Fermat spiral scan. @@ -306,6 +311,9 @@ class OmnyFermatScan(ScanBase): step(float): stepsize spiral_type(int): 0 for traditional Fermat spiral center(bool): whether to include the center position + cenx(float): center offset in x + ceny(float): center offset in y + zshift(float): shift in z Returns: positions(array): positions @@ -319,7 +327,7 @@ class OmnyFermatScan(ScanBase): length_axis2 = np.abs(m2_stop - m2_start) n_max = int(length_axis1 * length_axis2 * 3.2 / step / step) - z_pos = self.zshift + z_pos = zshift for ii in range(start, n_max): radius = step * 0.57 * np.sqrt(ii) @@ -330,17 +338,9 @@ class OmnyFermatScan(ScanBase): continue x = radius * np.sin(ii * phi) y = radius * np.cos(ii * phi) - positions.append([x + self.cenx, y + self.ceny, z_pos]) - left_lower_corner = [ - min(m1_start, m1_stop) + self.cenx, - min(m2_start, m2_stop) + self.ceny, - z_pos, - ] - right_upper_corner = [ - max(m1_start, m1_stop) + self.cenx, - max(m2_start, m2_stop) + self.ceny, - z_pos, - ] + positions.append([x + cenx, y + ceny, z_pos]) + left_lower_corner = [min(m1_start, m1_stop) + cenx, min(m2_start, m2_stop) + ceny, z_pos] + right_upper_corner = [max(m1_start, m1_stop) + cenx, max(m2_start, m2_stop) + ceny, z_pos] positions.append(left_lower_corner) positions.append(right_upper_corner) return np.array(positions) diff --git a/tests/tests_bec_ipython_client/test_omny_tomo_angles.py b/tests/tests_bec_ipython_client/test_omny_tomo_angles.py index a9671af1..a3e1a411 100644 --- a/tests/tests_bec_ipython_client/test_omny_tomo_angles.py +++ b/tests/tests_bec_ipython_client/test_omny_tomo_angles.py @@ -387,3 +387,66 @@ def test_tomo_parameters_clamps_type_3_step_size_to_max_2_5_degrees(monkeypatch, assert omny.tomo_type == 3 assert omny.tomo_angle_stepsize == pytest.approx(2.5) + + +# --- tomo_parameters(): warns early about too few Fermat scan points -------- +# +# omny_fermat_scan.OmnyFermatScan.prepare_scan() aborts (ScanAbortion) when +# the FOV/step combination yields fewer than MIN_POSITIONS points -- that was +# already the intended behavior, but nothing warned the user ahead of time; +# the scan would just silently fail once actually run. Direct port of +# Flomni.tomo_parameters()'s identical warning line. + + +def test_tomo_parameters_warns_when_fermat_positions_below_minimum(monkeypatch, fake_bec, capsys): + fake_bec.active_account = "e00001" + omny = make_omny() + omny.tomo_countingtime = 1.0 + omny.tomo_shellstep = 50.0 # coarse step + tiny FOV -> too few points + omny.fovx = 1 + omny.fovy = 1 + omny.stitch_x = 0 + omny.stitch_y = 0 + omny.tomo_stitch_overlap = 0.2 + omny.ptycho_reconstruct_foldername = "queue" + omny.manual_shift_y = 0.0 + omny.tomo_angle_stepsize = 10.0 + omny.tomo_type = 1 + fake_dev = types.SimpleNamespace( + omny_samples=types.SimpleNamespace(get_sample_name_in_samplestage=lambda: "test_sample") + ) + monkeypatch.setattr(omny_module, "dev", fake_dev, raising=False) + omny.OMNYTools = types.SimpleNamespace(yesno=lambda *a, **k: True) # accept as-is, no edits + + omny.tomo_parameters() + + out = capsys.readouterr().out + assert "WARNING: below the minimum" in out + assert "the scan will abort when run" in out + + +def test_tomo_parameters_no_warning_when_fermat_positions_sufficient(monkeypatch, fake_bec, capsys): + fake_bec.active_account = "e00001" + omny = make_omny() + omny.tomo_countingtime = 1.0 + omny.tomo_shellstep = 0.5 + omny.fovx = 20 + omny.fovy = 20 + omny.stitch_x = 0 + omny.stitch_y = 0 + omny.tomo_stitch_overlap = 0.2 + omny.ptycho_reconstruct_foldername = "queue" + omny.manual_shift_y = 0.0 + omny.tomo_angle_stepsize = 10.0 + omny.tomo_type = 1 + fake_dev = types.SimpleNamespace( + omny_samples=types.SimpleNamespace(get_sample_name_in_samplestage=lambda: "test_sample") + ) + monkeypatch.setattr(omny_module, "dev", fake_dev, raising=False) + omny.OMNYTools = types.SimpleNamespace(yesno=lambda *a, **k: True) + + omny.tomo_parameters() + + out = capsys.readouterr().out + assert "WARNING: below the minimum" not in out + assert "Estimated Fermat scan points per projection:" in out diff --git a/tests/tests_bec_ipython_client/test_omny_tomo_scan.py b/tests/tests_bec_ipython_client/test_omny_tomo_scan.py index 202d3a20..2bda299d 100644 --- a/tests/tests_bec_ipython_client/test_omny_tomo_scan.py +++ b/tests/tests_bec_ipython_client/test_omny_tomo_scan.py @@ -125,6 +125,18 @@ def test_tomo_scan_shows_progress_gui(monkeypatch): assert calls == ["shown"] +def test_tomo_scan_accepts_interactive_kwarg(monkeypatch): + """TomoQueueMixin.tomo_queue_execute() always calls + self.tomo_scan(interactive=False) for unattended queued runs -- confirmed + live: OMNY.tomo_scan() didn't accept this kwarg at all, so every queued + job failed with 'got an unexpected keyword argument interactive'.""" + omny = make_omny_for_tomo_scan(monkeypatch, 45.0, active_account="") + + omny.tomo_scan(interactive=False) # must not raise TypeError + + assert omny.progress["tomo_start_time"] is not None + + def test_tomo_scan_clears_heartbeat_on_normal_completion(monkeypatch): """The busy-detector heartbeat must be cleared as soon as the scan finishes, not left for the next poll to time out before the GUI stops @@ -255,3 +267,30 @@ def test_write_to_scilog_tolerates_send_exception(monkeypatch): result = omny.write_to_scilog("hello") assert result is False + + +# --- _write_tomo_scan_number(): ~/data/raw/logs/, creating it if missing ---- +# +# Confirmed live: the old ~/Data10/specES1/dat-files/ path didn't exist at +# all on a fresh session (a Mac dev machine), crashing with +# FileNotFoundError the moment a real tomo scan tried to log its first +# projection. Moved to ~/data/raw/logs/ (matching flomni's own +# _write_tomo_scan_number()) and, unlike flomni's identical open("a+") call, +# explicitly create the directory first rather than assume it already +# exists. + + +def test_write_tomo_scan_number_creates_missing_directory(monkeypatch, tmp_path): + monkeypatch.setenv("HOME", str(tmp_path)) + omny = object.__new__(OMNY) + omny.tomo_id = 1 + fake_dev = types.SimpleNamespace( + osamroy=types.SimpleNamespace(read=lambda: {"osamroy": {"value": 12.5}}), + omny_samples=types.SimpleNamespace(get_sample_name_in_samplestage=lambda: "test_sample"), + ) + monkeypatch.setattr(omny_module, "dev", fake_dev, raising=False) + + omny._write_tomo_scan_number(844, 12.5, 1) + + written = (tmp_path / "data" / "raw" / "logs" / "tomography_scannumbers.txt").read_text() + assert written == "844 12.5 12.500 1 1 0 test_sample\n" diff --git a/tests/tests_scans/test_omny_fermat_scan.py b/tests/tests_scans/test_omny_fermat_scan.py index f403fcad..f17c7498 100644 --- a/tests/tests_scans/test_omny_fermat_scan.py +++ b/tests/tests_scans/test_omny_fermat_scan.py @@ -1,6 +1,7 @@ from unittest import mock import numpy as np +import pytest from csaxs_bec.scans.omny_fermat_scan import OmnyFermatScan @@ -74,3 +75,61 @@ def test_estimate_corridor_size_scales_with_factor(): doubled_factor = OmnyFermatScan._estimate_corridor_size(positions, factor=3.0) assert np.isclose(doubled_factor, 2 * default_factor) + + +def test_min_positions_matches_flomni(): + """OmnyFermatScan.MIN_POSITIONS must exist as a class constant (not a + hardcoded literal in prepare_scan()) so OMNY.tomo_parameters() can warn + early against the same threshold the scan server actually enforces, + mirroring FlomniFermatScan.MIN_POSITIONS.""" + assert OmnyFermatScan.MIN_POSITIONS == 20 + + +def test_get_omny_fermat_spiral_pos_is_static_and_callable_without_an_instance(): + """Ported to a @staticmethod (was an instance method reading + self.cenx/self.ceny/self.zshift) so OMNY.tomo_parameters() can call it + directly (via the class, like Flomni._expected_fermat_position_count() + does with FlomniFermatScan.get_flomni_fermat_spiral_pos()) without + constructing a full scan instance.""" + positions = OmnyFermatScan.get_omny_fermat_spiral_pos(-5, 5, -5, 5, step=1, spiral_type=0) + assert len(positions) > 0 + + +def test_get_omny_fermat_spiral_pos_count_ignores_cenx_ceny_zshift(): + """cenx/ceny/zshift only shift the final position (applied after the + FOV keep-or-discard check), so they must never change the resulting + position count -- same invariant flomni's version relies on.""" + baseline = OmnyFermatScan.get_omny_fermat_spiral_pos(-5, 5, -5, 5, step=1, spiral_type=0) + shifted = OmnyFermatScan.get_omny_fermat_spiral_pos( + -5, 5, -5, 5, step=1, spiral_type=0, cenx=100.0, ceny=-50.0, zshift=7.0 + ) + + assert len(shifted) == len(baseline) + # the offset is applied uniformly to every returned position + assert np.allclose(shifted[:, 0] - baseline[:, 0], 100.0) + assert np.allclose(shifted[:, 1] - baseline[:, 1], -50.0) + assert np.allclose(shifted[:, 2], 7.0) + + +def test_prepare_scan_aborts_below_min_positions(): + """Regression guard for the MIN_POSITIONS refactor: prepare_scan() must + still reject a too-small FOV/step combination the same way it did with + the old hardcoded literal.""" + from bec_server.scan_server.errors import ScanAbortion + + scan = mock.MagicMock() + scan.fovx = 1 + scan.fovy = 1 + scan.step = 1 + scan.zshift = 0 + scan.cenx = 0 + scan.ceny = 0 + scan.corridor_size = None + scan.MIN_POSITIONS = OmnyFermatScan.MIN_POSITIONS + # get_omny_fermat_spiral_pos is now a @staticmethod -- bind the real + # function so prepare_scan()'s self.get_omny_fermat_spiral_pos(...) call + # runs the actual math instead of an auto-mocked stand-in. + scan.get_omny_fermat_spiral_pos = OmnyFermatScan.get_omny_fermat_spiral_pos + + with pytest.raises(ScanAbortion): + OmnyFermatScan.prepare_scan(scan)