URL encoding
Warning
It is generally advised that users leverage the explorer module of siibra-python to encode and decode URL.
siibra-explorer achieves state persistence via URL encoding.
Basics
State that are persisted is first serialized to string. These string are then prefixed by the label representing the string. The list is joined with / as a delimiter.
The resultant string is then prepended by <path_to_viewer>#/, where <path_to_viewer> is usually https://atlases.ebrains.eu/viewer/.
Example
User navigated to the following viewer configuration
| state | prefix | value | serialized | prefix + serialized |
|---|---|---|---|---|
| atlas | a: |
Multilevel Human Atlas | juelich:iav:atlas:v1.0.0:1 |
a:juelich:iav:atlas:v1.0.0:1 |
| space | t: |
ICBM 2009c nonlinear asymmetrical | minds:core:referencespace:v1.0.0:dafcffc5-4826-4bf1-8ff6-46b8a31ff8e2 |
t:minds:core:referencespace:v1.0.0:dafcffc5-4826-4bf1-8ff6-46b8a31ff8e2 |
| parcellation | p: |
Julich Brain v3.0.3 | minds:core:parcellationatlas:v1.0.0:94c1125b-b87e-45e4-901c-00daee7f2579-300 |
p:minds:core:parcellationatlas:v1.0.0:94c1125b-b87e-45e4-901c-00daee7f2579-300 |
The URL would be
https://atlases.ebrains.eu/viewer/#/a:juelich:iav:atlas:v1.0.0:1/t:minds:core:referencespace:v1.0.0:dafcffc5-4826-4bf1-8ff6-46b8a31ff8e2/p:minds:core:parcellationatlas:v1.0.0:94c1125b-b87e-45e4-901c-00daee7f2579-300
Escaping Characters
As / character is used to separate state, it is escaped to :.
References
Here is a comprehensive list of the state encoded in the URL:
| selected state | prefix | value | example |
|---|---|---|---|
| atlas | a: |
id property | |
| parcellation | p: |
id property | |
| space | t: |
id property | |
| region | rn: |
Quick hash of region name1 | |
| geometry | g: |
Serialized selected geometry of interest2 | /g:v1.0.3CfEFg.1AgkO0 |
| navigation | @: |
navigation state hash3 | |
| feature | f: |
id property + additional escaping4 | |
| misc viewer state | vs: |
misc viewer state serialization5 | |
| auto launch plugin | pl (query param) |
stringified JSON representing string[] |
?pl=%5B%22http%3A%2F%2Flocalhost%3A1234%2Fmanifest.json%22%5D . Modern browsers also accept ?pl=["http://localhost:1234/manifest.json"] |
-
Quick hash. [source] Quick one way hash. It will likely be deprecated in favor of crypto.digest in the near future. ↩
-
Encoding geometry of interest. Only selected point is supported. Each coordinate is base64 encoded The number is base64 encodded [source]. The final value is in the form of
v1.{encoded_x}.{encoded_y}.{encoded_z}. ↩ -
Encoding navigation state. [source] Each of the following state are encoded:
orientation,perspectiveOrientation,perspectiveZoom,position,zoom. They are cast into[f32, f32, f32, f32],[f32, f32, f32, f32],int,[int, int, int]andintrespective. Each of the number is base64 encoded [source] with the following cipher:0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_-. Negation is denoted using~as the beginning of encoded value. If the state consists of a tuple of values, they are joined by a single separator (i.e.:). The encoded state is then joined with two separators (i.e.::) ↩ -
additional feature id escaping: since feature id can be a lot more varied, they are further encoded by: first instance of
://is replaced with~ptc~; all instances of:is replaced with~; any occurances[()]are URL encoded. ↩ -
miscellaneous viewer state serialization. [source] Various viewer configuration related state is encoded. This encoded state is versioned, in order to preserve backwards compatibility. The current version is
v1. In the current version, threeuint8values are base64 encoded. First encodes for panel mode ( four-panel,FOUR_PANEL, encoded as1;PIP_PANEL, encoded as2). Second encodes for panel order. Third encodes for the bit masked boolean flags for octant removal and show delination, with the remaining 6 bits ignored. ↩