Developers
The developer version in PyReconstruct integrates tracing contours with ongoing machine-guided segmentation efforts in our lab. You can export images and contours via the command line as labeled zarrs that can be viewed in Neuroglancer, which is included.
Currently, the developer version is available in Linux/macOS, but can be run through WSL (Windows Subsystem for Linux) in Windows 11.
Make sure you have git, gcc, make, and conda packages and the realpath command before setting up the dev version of PyReconstruct.
(In macOS, Homebrew is an easy-to-use tool for installing packages. For example, install gcc with Homebrew: brew install gcc. The realpath command comes with the coreutils package: brew install coreutils.)
Clone the repo and change your working directory:
git clone https://github.com/synapseweb/PyReconstruct
cd PyReconstruct/dev
Take a look at the Makefile options:
make
Create the environment:
make env
(You can change the default name of the virtual environment by modifying ENV_NAME in the Makefile before running make env.)
link_shell.sh, which is executed when making the environment, adds commands, modifies pre- and post-environment activation hooks, and amends sys.path to include the repo root. To check that these scripts were linked properly during the process of making the environment, we have included a simple test command, which should produce output to the terminal. Test it by running the following:
conda activate pyrecon_dev
yas-queens
Should the above fail, make sure the virtual environment is activated and manually source the script:
conda activate pyrecon_dev
ENV_DIR=$CONDA_PREFIX source link_shell.sh
Finally, re-run the test command above.
Activate the virtual environment and launch PyReconstruct:
conda activate pyrecon_dev
PyReconstruct
(Note: PyReconstruct is also aliased to pyrecon and pr. make env will not overwrite aliases already present in your terminal.)
Wayland, a modern alternative to the ubiqitous X Window System, is become increasingly popular. PyReconstruct can be run under Wayland, but opening the 3D scene might cause it to crash. Get around this by lauching PyReconstruct in X. Simply set the QT platform variable to xcb:
conda activate pyrecon_dev
QT_QPA_PLATFORM=xcb PyReconstruct
Series images can be exported as zarrs with labels representing PyReconstruct object groups. Exported zarrs are compatible with Neuroglancer. The steps below walk you through creating a zarr from a jser file.
Check your series images.
Make sure the jser for your series points to a valid directory containing series images (tif, jpg, zarr, etc). You can change the image directory in PyReconstruct by going to Series → Images → Find/change image directory in the menu.
You can also set the image directory directly in the jser, for example, with the json command line tool jq:
example_series=~/my_series.jser
temp_file=$(mktemp)
jq '.series.src_dir = "~/new_image_dir"' $example_series > $temp_file
mv $temp_file $example_series
Add objects to groups.
Object groups in PyReconstruct can be converted to labels in zarrs. Assign objects in PyReconstruct to an object group by opening the object list (Lists → Object list, shortcut: Ctrl/Cmd+Shift+O). Right click on each object and add to a group. For example, select all dendrites, right click, and assign to a new group named "dendrites".
The command to export to zarr is ng-create-zarr. View its options and arguments:
ng-create-zarr --help
This command takes a single argument, the filepath to the jser, and accepts multiple options.
For example, the following exports my_series.jser to zarr and creates a label for all objects in the group dendrites.
ng-create-zarr ~/zarr_me_up_scotty/my_series.jser --groups dendrites
You can also export multiple groups as labels, assuming the groups exist in the jser file.
ng-create-zarr ~/zarr_me_up_scotty/my_series.jser --groups dendrites spines
Images are exported to a zarr dataset named raw and groups are exported as datasets named labels_<group>.
Omitting the --groups flag will produce a zarr with no labels.
Note: The above commands might fail on display-less systems, for example, if you are attempting to convert series to zarrs on remote servers. To get around this, simply set the QT platform variable to offscreen.
QT_QPA_PLATFORM=offscreen ng-create-zarr ~/zarr_me_up_scotty/my_series.jser --groups dendrites
By default, the zarr is exported to the directory containing the jser file and is named according to its window (in other words, its bounding box): data-<window>.
You can specify an output path using the --output flag:
# Export zarr named "exported_zarr" to home directory
ng-create-zarr ~/zarr_me_up_scotty/my_series.jser --groups dendrites --output ~/exported_zarr
ng-create-zarr will export a zarr delimited by a bounding box that includes all objects in each of the specified groups. The zarr will contain as many sections as the objects appear on.
Contours are generally drawn along the middle of the plasma membrane, and creating a bounding box based on the contours alone would result in a zarr containing partial membranes. To get around this, a 50-pixel padding is added by default around group objects.
The default padding can be changed with the --padding flag:
# Increase padding to 100 px
ng-create-zarr ~/zarr_me_up_scotty/my_series.jser --groups dendrites spines --padding 100
# Remove padding completely
ng-create-zarr ~/zarr_me_up_scotty/my_series.jser --groups dendrites spines --padding 0
You can also create a zarr using all available tissue using the --max_tissue flag. This will create a zarr bounded by the minimum and maximum x and y values of all images in the stack. All available sections are included in the zarr; however, we assume section 0 includes a calibration grid, which is excluded by default from the exported volume.
# Use all imaged tissue
ng-create-zarr ~/zarr_me_up_scotty/my_series.jser --groups dendrites spines --max_tissue
To view your exported zarr, Neuroglancer has been bundled with the developer version of PyReconstruct:
ng-view-zarr my_series.zarr
Once generated, the link can be opened in your browser. Do not close the interactive Python session until you're done viewing the zarr.
You can also specify datasets using the neuroglancer command:
neuroglancer -f ~/my_series.zarr -d raw labels_dendrites
Be aware that a trailing slash after the zarr filepath is problematic with this command.
# No trailing slash after filepath: Works great!
neuroglancer -f ~/my_series.zarr -d raw labels_dendrites
# Trailing slash after filepath: Will cause you to rip your hair out.
neuroglancer -f ~/my_series.zarr/ -d raw labels_dendrites