From 562f4918f8ba5dde2481c4af22c54284c8f068a2 Mon Sep 17 00:00:00 2001 From: Matias Guijarro Date: Thu, 5 May 2022 11:27:54 +0200 Subject: [PATCH] doc: improve documentation about 'user_scan_meta' --- doc/docs/data/data_scan_metadata.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/doc/docs/data/data_scan_metadata.md b/doc/docs/data/data_scan_metadata.md index 8dc9eb1d4d..965da53ce6 100644 --- a/doc/docs/data/data_scan_metadata.md +++ b/doc/docs/data/data_scan_metadata.md @@ -23,7 +23,20 @@ You can register metadata generators in the setup of a BLISS session, which will The `get_user_scan_meta()` function from `bliss.scanning.scan_meta` returns the scan metadata object. Each metadata category is accessible via the corresponding property. -Then, the `.set()` method allows to associate a name or an object with a `.name` property + +The metadata category has a `timing` property, which allows to select when metadata has +to be taken. `timing` can be a combination of: + +- `scan_meta.META_TIMING.START` + - will be called at the beginning of the scan +- `scan_meta.META_TIMING.END` + - will be called at the end of the scan +- `scan_meta.META_TIMING.PREPARED` + - will be called when the scan has been prepared (not started yet) + +Default timing in general is START. Default timing for `instrument` category is END. + +Then, the `.set()` method allows to associate a name (or an object with a `.name` property) to a function, that has to return a dictionary to be stored as metadata for the object, for the category. @@ -59,3 +72,12 @@ scan_meta_obj.instrument.set("mymetadata", {"myattenuator": "thickness": 20., "thickness@units": "um") ``` + +!!! note + User scan meta are collected **for each scan**. In particular, in case of dynamic metadata (when a + callback function returns a dictionary), the scan object is passed to be able to + select whether metadata has to be returned or not. + +!!! note + Do not forget to remove items, if they are not needed. This can be done with `.remove()` on + the different categories. -- GitLab