{"id":29551349,"url":"https://github.com/aplbrain/bossvr","last_synced_at":"2026-03-07T18:31:28.295Z","repository":{"id":295140442,"uuid":"818300390","full_name":"aplbrain/bossVR","owner":"aplbrain","description":"Syglass + BossDB ","archived":false,"fork":false,"pushed_at":"2025-06-02T13:52:17.000Z","size":22279,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-07-18T06:32:45.775Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aplbrain.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-06-21T14:35:34.000Z","updated_at":"2025-06-02T13:52:21.000Z","dependencies_parsed_at":"2025-07-18T05:29:13.357Z","dependency_job_id":"21c4c9e4-8b90-4547-a048-0cfb5a277229","html_url":"https://github.com/aplbrain/bossVR","commit_stats":null,"previous_names":["aplbrain/bossvr"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aplbrain/bossVR","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aplbrain%2FbossVR","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aplbrain%2FbossVR/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aplbrain%2FbossVR/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aplbrain%2FbossVR/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aplbrain","download_url":"https://codeload.github.com/aplbrain/bossVR/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aplbrain%2FbossVR/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30226246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T18:12:09.766Z","status":"ssl_error","status_checked_at":"2026-03-07T18:11:58.786Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-18T04:05:45.228Z","updated_at":"2026-03-07T18:31:28.260Z","avatar_url":"https://github.com/aplbrain.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BossVR\nhttps://github.com/user-attachments/assets/359d64c9-5494-4d80-8e8d-05bc388210b9\n\n**BossVR** is a Python tool that allows you to interact with datasets from [BossDB](https://bossdb.org/projects) and create or modify [syGlass](https://www.syglass.io/) projects. This tool is designed to retrieve information about datasets, download images in TIFF format, download and transform meshes, create syGlass projects with image stacks, mask layers, and meshes, and upload and export annotations.\n\n## Features\n\n- **Dataset Information Retrieval**: Extract detailed information about your datasets from BossDB.\n- **Image and Mesh Downloading**: Download images and meshes from BossDB in the desired format and resolution.\n- **syGlass Project Creation**: Create syGlass projects with multiple layers, including images, masks, and meshes.\n- **Annotation Management**: Export and import annotations and tracings for syGlass projects.\n- **Shader Settings Management**: Export and apply shader settings in syGlass projects.\n\n## Requirements\n\nInstall the required packages using the `requirements.txt` file:\n\n```sh\npip install -r requirements.txt\n```\n\nAlternatively, set up a new environment with the `bossVR.yaml` file:\n\n```sh\nconda env create -f bossVR.yaml\n```\n\nThis tool supports both `intern` and `CloudVolume` for accessing BossDB data. Follow the installation instructions for [intern](https://github.com/jhuapl-boss/intern) and [CloudVolume](https://github.com/seung-lab/cloud-volume?tab=readme-ov-file) for detailed guidance.\n\n## Available Functions\n\n### Config Module\n- **BaseConfig**: Handles the configuration settings for the tool, including dataset dimensions, paths, and project details.\n\n### Pipeline Module\n\n- **ExtractInfo**: Retrieves detailed information about datasets from BossDB.\n  - `cloud_info(data_type='image')`: Retrieves and displays the available resolutions and dimensions for image or segmentation data.\n\n- **ImageDownload**: Downloads images from BossDB and saves them in TIFF format.\n  - `cloud_convert(data_type='image')`: Downloads cutout data from BossDB and saves it as TIFF files. Can operate on both image and segmentation stacks.\n  - The dimensions for image download are specified in the configuration file, but are automatically calculated for the segmentation (ex. if both are not in the same resolution). \n \n- **Annotations**: Manage annotations including extraction, importing, volumetric block operations, and ROI handling.\n  - `extract_tracking_points()`: Extracts tracking points from a syGlass project as a 'CAVE annotation table'-like DataFrame. \n  - `import_tracking_points(df)`: Imports tracking points from a 'CAVE annotation table'-like DataFrame into a syGlass project.\n  - `get_all_volumetric_blocks()`: Retrieves all volumetric blocks around tracking points. Returns a list of syGlass `blocks`. \n  - `get_volumetric_block_around_point(block_num)`: Retrieves a specific volumetric block centered around a particular tracking point, and converts it into a TIFF stack. `block_num` denotes the index of the block, as numbered in the counting point annotation table.\n  - `export_tracings()`: Exports tracings to SWC files in the directory. \n  - `import_tracings(trace_file_path)`: Imports tracings from SWC files.\n  - `export_roi(roi_index)`: Exports ROI data as TIFF. Indexed by ROI index. \n  - `import_roi(roi_index, roi_mask)`: Imports ROI data as a mask numpy array. \n\n- **MeshDownload**: Downloads and transforms meshes from BossDB.\n  - `download_meshes_cave(mesh_file_location)`: Downloads meshes using the CAVEclient.\n  - `download_meshes_cv(mesh_file_location)`: Downloads meshes using CloudVolume.\n  - `transform_meshes(mesh_file_location)`: Transforms mesh coordinates based on the dataset's resolution and dimensions, to co-register with the image stacks in the syGlass project.\n  - `run_mesh_download()`: Executes the mesh download and transformation process.\n\n- **ProjectCreation**: Handles the creation and modification of syGlass projects.\n  - `create_base_project(first_img_image)`: Creates a new syGlass project with the downloaded image stack.\n  - `add_mask_layer(proj_file_location, first_seg_image)`: Adds a mask layer to the existing syGlass project.\n  - `add_mesh_objs(proj_file_location, mesh_file_location)`: Adds mesh objects to the existing syGlass project.\n\n- **ShaderSettings**: Manages shader settings for syGlass projects.\n  - `export_shader_settings()`: Exports shader settings from a syGlass project as a JSON file. Saves the file in ./output_file_path/shader_settings/project_name_shader_settings.json\n  - `apply_view_shader_settings()`: Opens the syGlass project with the specific shader settings JSON specified in config.ini\n  - `open_project()`: Opens a syGlass project.\n\n### Util Module\n\n**common_functions**: Provides utility functions for image processing, file handling, and other tasks.\n\n- `save_slices_as_tiff(dataset, path, file_location, offset, data_type='')`: \n  Saves image slices from a 3D dataset as TIFF files. The function supports both block-based and standard image stacks and handles image rotation and flipping to transform image orientation consistent with how images are loaded in syGlass\n\n- `get_pair_indices(index, dim, vol, indices)`: \n  Parses and validates index ranges for a given dimension of a 3D volume, ensuring the range is within the volume bounds.\n\n- `get_indices(vol, x_indices, y_indices, z_indices)`: \n  Retrieves and validates the start and stop indices for the X, Y, and Z dimensions of a 3D volume.\n\n- `parse_url(url)`: \n  Parses a URL to ensure it contains the correct format for accessing a dataset from BossDB with CloudVolume.\n\n- `check_res_cloud(img_uri, img_res, seg_uri, seg_res)`: \n  Checks if the resolution of image and segmentation data match. If they don't, it raises a warning and suggests downsampling the larger dataset.\n\n- `transform_annotation_points(vertex, img_resolution, x, y, z)`: \n  Transforms annotation points from the syGlass real-world coordinate system to the dataset coordinate system of voxels.\n\n## Configuration\n\nTo run the script, modify the parameters in the configuration file named `config.ini`, located in the same directory as the script:\n\n- `img_uri`: CloudVolume image data URI. Required.\n- `img_res`: Desired resolution for image data. By default, `img_res=0`.\n- `seg_uri`: CloudVolume segmentation data URI.\n- `seg_res`: Desired resolution for segmentation data. By default, `seg_res=0`.\n- `x_dimensions`: Range for X dimension in the format `x_start:x_stop`. If not provided, the entire range is extracted.\n- `y_dimensions`: Range for Y dimension in the format `y_start:y_stop`. If not provided, the entire range is extracted.\n- `z_dimensions`: Range for Z dimension in the format `z_start:z_stop`. If not provided, the entire range is extracted.\n- `output_path`: Directory where the images, segmentations, meshes, and syGlass project should be saved. If not provided, images will be saved in the default directory.\n- `CAVEclient`: Name of the CAVEclient bucket to pull meshes from. Optional.\n- `mesh_ids`: List of mesh IDs to be downloaded and transformed. Required for downloading meshes. Otherwise optional.\n- `mesh_uri`: CloudVolume URI to pull meshes from. If both `mesh_uri` and `CAVEclient` are provided, the script by default will use `CAVEclient`.\n- `project_name`: Desired name of the project. Required.\n- `syglass_directory`: File path to the syGlass installation. Folder containing built-in `syGlassCLI.exe`. Required for importing and exporting shader settings. Otherwise optional.\n- `shader_settings_to_load_path`: File path to the JSON file of shader settings to load in the created project.\n\nExample `config.ini` file:\n\n```ini\n[DEFAULT]\nimg_uri = yim_choe_bae2023/dauer1_364/em/em\nimg_res = 0 \nseg = True \nseg_uri = yim_choe_bae2023/dauer1_364/seg_oct22\nseg_res = 0  \nx_dimensions = 600:9300\ny_dimensions = 500:9600\nz_dimensions = 0:364\noutput_path = ./yimchoebae\nCAVEclient = \nmesh_ids = [1, 100, 101, 99]\nmesh_uri = bae2024/dauer1/mito_seg_v4\nproject_name = yim_choe_bae2023_project\nsyglass_directory = C:/Program Files/syGlass/bin\nshader_settings_to_load_path = ./shader_settings/shaderSettings.json\n```\n\n## CLI Usage\n\nThe `main.py` script can be executed from the command line to perform the commands below tasks. The dataset and project parameters must be specified in the config.ini file. \n\n### Available Commands\n\n- **extract_img_info**: Retrieves image dataset information.\n- **extract_seg_info**: Retrieves segmentation dataset information.\n- **download_img**: Downloads images as a TIFF stack.\n- **download_seg**: Downloads segmentation images as a TIFF stack.\n- **run_mesh_download**: Downloads and transforms meshes, co-registered to the image and segmentation stacks\n- **create_project_only_img**: Creates a project with just the images.\n- **create_project_img_mesh**: Creates a project with images and meshes.\n- **create_project_img_seg_mesh**: Creates a project with images, segmentation masks, and meshes.\n- **export_shader_settings**: Exports shader settings as a JSON.\n- **apply_view_shader_settings**: Opens project in specified shader settings.\n- **open_project**: Opens a syGlass project.\n- **export_tracking_points**: Exports annotation points as a dataframe.\n- **import_tracking_points**: Imports annotation points from a dataframe.\n- **get_all_volumetric_blocks**: Retrieves all volumetric blocks from counting points in the project.\n- **get_volumetric_block_around_point**: Retrieves a specific volumetric block centered around a tracking point. Requires `--block_num`.\n- **export_tracings**: Exports tracings as SWC files.\n- **import_tracings**: Imports tracings from SWC files.\n- **export_roi**: Exports ROI data as TIFF. Requires `--roi_index`.\n- **import_roi**: Imports ROI data as a mask numpy array. Requires `--roi_index` and `--roi_mask`.\n\n### Example Usage\n\n1. **Extract Dataset Information**:\n   ```sh\n   python main.py extract_img_info\n   python main.py extract_seg_info\n   ```\n\n2. **Download Images and Meshes**:\n   ```sh\n   python main.py download_img\n   python main.py download_seg\n   python main.py run_mesh_download\n   ```\n\n3. **Create syGlass Project**:\n   ```sh\n   python main.py create_project_only_img\n   python main.py create_project_img_mesh\n   python main.py create_project_img_seg_mesh\n   ```\n\n4. **Manage Annotations**:\n   ```sh\n   python main.py export_tracking_points\n   python main.py import_tracking_points --data_frame_path path_to_dataframe\n   python main.py get_all_volumetric_blocks\n   python main.py get_volumetric_block_around_point --block_num 5\n   python main.py export_tracings\n   python main.py import_tracings --trace_file_path path_to_tracings\n   python main.py export_roi --roi_index 1\n   python main.py import_roi --roi_index 1 --roi_mask path_to_roi_mask\n   ```\n\n5. **Manage Shader Settings**:\n   ```sh\n   python main.py export_shader_settings\n   python main.py apply_view_shader_settings\n   python main.py open_project\n   ```\n\n**Notes/Future Improvements**: \n1. The project creation steps may raise errors if syGlass believes a project is still open, or for other  reasons. In such cases, download the images, segmentations, meshes as individual steps, and manually upload to syGlass, specifying the voxel resolution.\n2. The project creation tools with pyGlass require a Windows operating system.\n3. When importing and exporting annotations, the project cannot be actively open in syGlass simultaneously.\n4. To use `apply_view_shader_settings()`, the project must already be in the syGlass project directory. The function only renders the project in the specified shader settings, but does not automatically save the project with them. To save the settings to the project, this must be done in syGlass.\n5. Further testing needed for export ROI as TIFF stack function\n6. Export tracings as .SWC functionality occassionally crashes if syGlass thinks a project is open\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faplbrain%2Fbossvr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faplbrain%2Fbossvr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faplbrain%2Fbossvr/lists"}