You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Since siibra creates many objects in a typical workflow, the creation of objects is following a clear structure.
9
10
There are two main approaches of object creation:
10
11
11
12
1. Preconfigured objects, via the configuration module. This happens automatically for
12
-
- subclasses of `AtlasConcept`, if the class parameter `configuration_folder` points to a subfolder of siibra configuration repositories.
13
+
- subclasses of :class:`AtlasConcept`, if the class parameter :attr:`configuration_folder` points to a subfolder of siibra configuration repositories.
13
14
- subclasses of `Feature`, if the class parameter `configuration_folder` points to a subfolder of siibra configuration repositories.
14
15
the implementation of these queries is centralized in `AtlasConcept.get_instances()` and `Feature.get_instances()`, respectively,
15
16
and relies on the registrations done in `AtlasConcept.__init_subclass__()` and `Feature.__init_subclass__()`.
17
+
16
18
2. Live queries, via the livequery module. This applies to subclasses of `Feature`, and relies on subclasses of `LiveQuery`
17
19
with the class parameter `FeatureType` set to the corresponding subclass of `Feature`. This triggers the query to be registered
18
20
in the `Feature._live_queries` list via `LiveQuery.__init_subclass__()`. Any registered live queries will then automatically be called
@@ -25,12 +27,13 @@ Instances of `Feature` subclasses are just stored as a list at class level.
25
27
26
28
27
29
Frequently used design patterns
28
-
-------------------------------
30
+
===============================
29
31
30
32
``siibra`` makes frequent use of some typical design patterns.
31
33
32
34
33
-
**Importing local classes**
35
+
Importing local classes
36
+
-----------------------
34
37
35
38
Often, siibra implementations make use of classes from different siibra modules.
36
39
It is common Python practice to do all imports at the start of a file, and not locally inside functions / classes.
@@ -64,7 +67,8 @@ and use module imports in other python files.
64
67
However, this rule of thumb is not yet consistently implemented and verified in siibra.
65
68
66
69
67
-
**Lazy loading via object properties.**
70
+
Lazy loading via object properties
71
+
----------------------------------
68
72
69
73
Since siibra pre-configures many objects, of which the user will typically only use a few
70
74
(e.g. after filternig data features by brain regions), it is important that time and/or memory
@@ -89,64 +93,58 @@ following this scheme:
89
93
90
94
91
95
The design of volumes and fetching mechanism
92
-
--------------------------------------------
93
-
94
-
**Basic definitions and notes**
95
-
96
-
- Volume: is a complete 3D object, typically a complete brain.
97
-
- Volume provider: is a resource that provides access to volumes. A volume can have multiple
98
-
providers in different formats.
99
-
- Variant: refers to alternative representations of the same volume. (e.g. inflated surface)
100
-
- If the volume has variants, they need to be listed in the configuration file.
101
-
- Fragments: are individually addressable components of a volume.
102
-
- If a volume has fragments, either the user or the code needs to retrieve from multiple
103
-
sources to access the complete volume.
104
-
- Fragments need to be named (e.g. left and right hemisphere), because they inevitably
105
-
split the whole object into distinct anatomical parts that require semantic labeling.
106
-
- Brain regions (label): are structures mapped inside a specific volume or fragment.
107
-
- The structure appears by interpreting the labels inside the volume listed in the
108
-
configuration file.
109
-
- In special cases, a brain region could be represented by the complete volume or
110
-
fragment.
111
-
- Volume index: the index of the volume in case there is more than one; typically used for
112
-
probability maps, where each area has a different volume.
113
-
- Z: for 4D volumes, it specifies the 4th coordinate identifying an actual 3D volume. It has
114
-
a similar function as the volume index, only that the volumes are concatenated in one array and
115
-
share the same affine transformation.
116
-
- Source type (format): the format of the volume data.
117
-
- See PREFERRED_FORMATS and SURFACE_FORMATS at volumes.volume.py for the currently
118
-
supported formats.
119
-
120
-
**Fetching volumes**
96
+
============================================
97
+
98
+
Basic definitions and notes
99
+
---------------------------
100
+
101
+
**Volume:** is a complete 3D object, typically a complete brain.
102
+
103
+
**Volume provider:** is a resource that provides access to volumes. A volume can have multiple providers in different formats.
104
+
105
+
**Variant:** refers to alternative representations of the same volume. (e.g. inflated surface).
106
+
107
+
* If the volume has variants, they need to be listed in the configuration file.
108
+
109
+
**Fragments:** are individually addressable components of a volume.
110
+
111
+
* If a volume has fragments, either the user or the code needs to retrieve from multiple sources to access the complete volume.
112
+
* Fragments need to be named (e.g. left and right hemisphere), because they inevitably split the whole object into distinct anatomical parts that require semantic labeling.
113
+
114
+
**Brain regions (label):** are structures mapped inside a specific volume or fragment.
115
+
116
+
* The structure appears by interpreting the labels inside the volume listed in the configuration file.
117
+
* In special cases, a brain region could be represented by the complete volume or fragment.
118
+
119
+
**Volume index:** the index of the volume in case there is more than one; typically used for probability maps, where each area has a different volume.
120
+
121
+
**Z:** for 4D volumes, it specifies the 4th coordinate identifying an actual 3D volume. It has a similar function as the volume index, only that the volumes are concatenated in one array and share the same affine transformation.
122
+
123
+
**Source type (format):** the format of the volume data.
124
+
125
+
* See :data:`SUPPORTED_FORMATS` (:data:`IMAGE_FORMATS` and :data:`SURFACE_FORMATS`) at volumes.volume.py for the currently supported formats.
126
+
127
+
Fetching volumes
128
+
----------------
121
129
122
130
Fetching volumes occurs in two main stages:
131
+
123
132
1) The determination of the volume by the user
124
-
- The user sets the object they would like to fetch a volume from:
125
-
i) a space template -> using get_template() which provides a volume template.
126
-
ii) or a map -> getting the desired map by setting desired specs.
127
-
- The user invokes fetch() method to retrieve the volume from the template or map.
128
-
i) template directly access to volume.fetch()
129
-
ii) fetch() first goes through map.fetch()
130
-
2) Actual retrieval of the volume object by siibra after the user asks for the volume via
131
-
`fetch()` method. When fetch() is invoked it accesses to corresponding volume provider
132
-
based on the specifications given by volume index, fragment, z, label, variant, and format.
133
-
According to the source type, the provider invokes the correct class and fetches the
134
-
data accordingly.
135
-
136
-
Defaults:
137
-
- Volume with several variants: the first variant listed in the configuration is fetched.
138
-
The user is informed along with a list of possible variants.
139
-
- Volume with several fragments: All fragments are retrieved and combined to provide
140
-
the whole volume. (This may cause some array length issues on the user end so the user
141
-
should be informed. Potentially, this may be changed to fetch only the first fragment
142
-
along with info and a list of options.)
143
-
144
-
Implementation Notes:
145
-
- When adjusting to a new type of data or special cases, it is highly encouraged to use
146
-
one of the existing parameters.
147
-
- Always inform a user when there are options available and the default is chosen.
133
+
* The user sets the object they would like to fetch a volume from:
134
+
- a space template -> using `get_template()`` which provides a volume template.
135
+
- or a map -> getting the desired map by setting desired specs.
136
+
* The user invokes `fetch()`` method to retrieve the volume from the template or map.
137
+
* template directly access to `volume.fetch()`
138
+
* `fetch()` first goes through `map.fetch()`
139
+
2) Actual retrieval of the volume object by siibra after the user asks for the volume via `fetch()` method.
140
+
When `fetch()` is invoked it accesses to corresponding volume provider based on the specifications given by volume index, fragment, z, label, variant, and format. According to the source type, the provider invokes the correct class and fetches the data accordingly.
141
+
142
+
**Defaults:**
143
+
144
+
- Volume with several variants: the first variant listed in the configuration is fetched. The user is informed along with a list of possible variants.
145
+
- Volume with several fragments: All fragments are retrieved and combined to provide the whole volume. (This may cause some array length issues on the user end so the user should be informed. Potentially, this may be changed to fetch only the first fragment along with info and a list of options.)
148
146
149
-
TO-DO:
150
-
- Remove meshindex parameter from NGmesh and replace it with one of the other parameters.
151
-
- Implement a default way to list the variants and fragments?
152
-
- A new mesh_util module or a toolbox/extension to handle mesh-related computations?
147
+
**Implementation Notes**
148
+
149
+
- When adjusting to a new type of data or special cases, it is highly encouraged to use one of the existing parameters.
150
+
- Always inform a user when there are options available and the default is chosen.
0 commit comments