Parsing and generating FlyWire URLs

The modified neuroglancer used by FlyWire lets you share shortened URLs. We can both read these URLs to extract segment IDs and generate URLs to inject segment IDs or annotations.

First things first: if you haven’t already, please generate and save your chunkedgraph secret so that you can fetch FlyWire data.

Decoding URLs

>>> from fafbseg import flywire

>>> # Paste a shortened URL to decode it
>>> flywire.decode_url(
...     "https://ngl.flywire.ai/?json_url=https://globalv1.flywire-daf.com/nglstate/5492440108630016"
... )

{'layers': [{'source': 'precomputed://https://bossdb-open-data.s3.amazonaws.com/flywire/fafbv14',
   'type': 'image',
   'blend': 'default',
   'shaderControls': {},
   'name': 'Maryland (USA)-image'},
  {'source': 'graphene://https://prodv1.flywire-daf.com/segmentation/1.0/flywire_public',
   'type': 'segmentation_with_graph',
   'segments': ['720575940605214636', '720575940631693610'],
   'skeletonRendering': {'mode2d': 'lines_and_points', 'mode3d': 'lines'},
   'timestamp': '1679386201',
   'graphOperationMarker': [{'annotations': [], 'tags': []},
    {'annotations': [], 'tags': []}],
   'pathFinder': {'color': '#ffff00',
    'pathObject': {'annotationPath': {'annotations': [], 'tags': []},
     'hasPath': False}},
   'name': 'Public Release-segmentation_with_graph'}],
 'navigation': {'pose': {'position': {'voxelSize': [4, 4, 40],
    'voxelCoordinates': [158581, 72226, 2189]}},
  'zoomFactor': 4},
 'showDefaultAnnotations': False,
 'perspectiveZoom': 79,
 'jsonStateServer': 'https://globalv1.flywire-daf.com/nglstate/post',
 'selectedLayer': {'layer': 'Public Release-segmentation_with_graph'},
 'layout': 'xy-3d'}

The exemplary URL used above encodes the default scene when you open https://ngl.flywire.ai. It contains the EM image and the public release segmentation layer with two neurons (720575940605214636 and 720575940631693610) selected.

By default decode_url() returns a dictionary with the entire scene. If you need something more compact you can change the format of the output:

>>> flywire.decode_url(
...     "https://ngl.flywire.ai/?json_url=https://globalv1.flywire-daf.com/nglstate/5492440108630016",
...     format="dataframe",
... )

	segment	layer	visible
0	720575940605214636	Public Release-segmentation_with_graph	True
1	720575940631693610	Public Release-segmentation_with_graph	True

Encoding URLs

What about generating our own URLs? Easy! Lets start by recreating the same scene as we have above:

>>> url = flywire.encode_url(
...     segments=[720575940605214636, 720575940631693610], dataset="public"
... )
>>> url

'https://ngl.flywire.ai/?json_url=https://globalv1.flywire-daf.com/nglstate/5820193760608256'

Opening that URL should load a scene containing only those two neurons.

By-the-by: you can also open the URL straight away like so

>>> url = flywire.encode_url(
...     segments=[720575940605214636, 720575940631693610], dataset="public", open=True
... )

How about some colors?

>>> # Load neuron in red
>>> flywire.encode_url(
...     segments=[720575940605214636, 720575940631693610],
...     open=True,
...     seg_colors=["r", "g"],
...     dataset="public",
... )

'https://ngl.flywire.ai/?json_url=https://globalv1.flywire-daf.com/nglstate/4925525631959040'

We can also add x/y/z coordinates as annotations:

>>> flywire.encode_url(
...     segments=[720575940605214636, 720575940631693610],
...     annotations=[[124266, 53184, 2500], [124266, 53184, 2600], [124266, 53184, 2700]],
...     open=True,
...     seg_colors=["r", "g"],
...     dataset="public",
... )

'https://ngl.flywire.ai/?json_url=https://globalv1.flywire-daf.com/nglstate/6291373214924800'

You can also add skeletons (e.g. loaded from CATMAID) as annotations but that unfortunately slows down neuroglancer pretty quickly.

Check out fafbseg.flywire.encode_url() for full capabilities.