welcome to lever.js -- computational tools for live cell & organelle microscopy
leverjs is designed to read data directly from the microscope, with instant-on analysis and visualization for multichannel 3-D and 2-D timelapse image data. See it in action at https://leverjs.net. start your own server or launch the stand-alone with a single click, point it at your time-lapse images. tell it how you want to visualize, to analyze and to interact with your data, and with the data that others have chosen to share. lever.js runs as a stand-alone native application or client/server accessed and controlled via web browser and works with mac/windows/unix.
lever.js is intended to enable collaboration, and to enable ubiquitous interaction with the images and analysis. the goal is to bring together expertise in biology and medicine with microscopy and computation. the vision is of a community built around learning from images and data. new collaborators are always welcome, as are new users.
-andy cohen
andyrcohen 'at' outlook.com
https://bioimage.coe.drexel.edu
introduction
leverjs is a collection of tools for visualizing, segmenting, tracking, classifying, and managing metatadata from live cell microscopy time-lapse movies.
leverjs is written in nodejs/javascript (client-server visualization), c++ (tracking) and matlab (segmentation and classification). sqlite is used for data storage and communication between components. note that leverjs uses NVIDIA's CUDA API for many of its image processing tasks. if CUDA is not available, leverjs will fall back to a less accurate MATLAB implementations. CUDA is not available on the Mac. YMMV.
leverjs can be extended to support processing with any language that can use sqlite at a cost of re-implementing a small set of helper functions. for example, it would be quite straightforward to write segmentation results from Python into leverjs for visualization, tracking or classification.
NOTE: leverjs also includes a visualization tool for 3-d multi-channel microscopy called leversc. leversc can be found in the git repo under leverjs/leversc. the leversc viewer can be use interactive or programmatically from MATLAB or Python and includes a plugin for ImageJ/Java. leversc is also available in a separate repository here :: https://leverjs.net/leversc.
license
this is a preview release. this is for collaborators with Andy Cohen's (https://bioimage.coe.drexel.edu) group to have a chance to try out the new software, test features and provide feedback. a manuscript describing this work is being planned now. once that manuscript is published, the program will be released free and open source...(gpl? mit? bsd? suggestions welcome...) until then, the software is not yet licensed for redistribution, and is not intended for public use.
note that we are always looking to develop new collaborations, and that we are actively seeking new datasets and partners for testing and evaluating the leverjs software tools. if you are interested, please contact andy at the email listed top of page.
when the software is released, it will be licensed free and open source. I would prefer to release under the most permissive license possible -- in the course of this project I've had the good fortune to work closely with the SQLite codebase. SQLite is a computer engineering marvel, and the inclusion of a 'blessing' instead of a legal usage notice is something that resonated deeply (you can read it here: https://git-bioimage.coe.drexel.edu/opensource/leverjs/tree/master/matdb/sqlite3/sqlite3.c). One constraint is that we use the bioformats tool for reading microscope data directly, and that is licensed under the GPL. So, at least initially it seems likely we will stick to the GPL license. Please contact Andy if you have any input or feedback on this question.
Note the leversc visualization components will be released under the MIT license concurrent with acceptance of the manuscript currently in review.
INSTALLATION
prerequisites
-
install node.js (I suggest the latest 'LTS' version) from https://nodejs.org
-
on windows, install windows-build-tools package. start a powershell prompt as administrator, and run
npm install --global windows-build-tools --vs2015
after this completes (it takes a while) close the powershell prompt.
on mac, install xcode.
-
if you want to analyze the images, and you don't have matlab 2019b runtime installed, download and and run the mcr installer from here: https://www.mathworks.com/products/compiler/matlab-runtime.html
-
install git lfs support from https://git-lfs.github.com/
-
from a git terminal (node.js command prompt or mac/unix terminal window), run:
git lfs install
- leverjs uses mpi for the multi-processing the tracking. on linux, install mpich
sudo apt install mpich
on windows we include a version of mpi with leverjs. you may be prompted to open firewall ports.
installation
start a node.js command prompt (on mac or unix open a command prompt with node.js on the path) and run each of the following:
git clone --depth=1 https://git-bioimage.coe.drexel.edu/opensource/leverjs.git
git clone --depth=1 https://git-bioimage.coe.drexel.edu/opensource/leverUtilities.git
[Optional but recommended -- clone the hydra image processor. for windows/ubuntu machines (ubuntu support pending)
this provides gpu accelerated (NVIDIA Cuda) image processing. Improved filtering over the matlab implementations
provides more accurate results in general, so this is strongly recommended. Mac support not available yet
git clone --depth=1 https://git-bioimage.coe.drexel.edu/opensource/hydra-image-processor.git
note that after cloning you will need to register the tdrDelay.reg file on windows, and then restart your pc.]
cd leverjs
npm update
npm run postinstall
now you can start the server:
node server.js --port=3000 /path/to/.leverFiles
and browse to localhost:3000 using chrome, firefox or opera (any webgl2 compliant browser)
matlab configuration
there is a sampleStartup.m file in the leverjs/matlab folder. check the path settings in that file, and be sure it gets run before using leverjs (e.g. add it to your startup.m file). if you run from client-server (e.g. via the web browser) you will need to have matlab 2019b or the runtime. if you run your processing directly from matlab, then any version >= 2019b should suffice.
cell tracking challenge data
for working with the cell tracking challenge datasets there is a separate leverjs CTC git repository.
you will find many useful routines for importing and processing cell tracking challenge images in that repo.
image import
leverjs imports microscope files directly using bioformats (http://www.openmicroscopy.org/bio-formats/). All common microscope files can be imported this way. The import process generates a .LEVER file, an HDF5 file that we use for processing, and also generates visualization files that the image window uses to render the 2-D and 3-D image data. It is preferable to read directly from the microscope files. This gives us access to the metadata (e.g. pixel physical sizes, channel names, etc) and assures that the images are uncompressed. Import functionality is availalable through electron experiment window (from the image window, click the lever icon to go back to the experiment window). There is an import tab. Enter the folder name where the microscope files are -- it will find all microscope files in that folder and all subfolders.
Programmatically, this functionality is available through matlab/+Import/leverImport
It is possible to import tiff files, but that requires a separate script. There is an example in matlab/+Import/convertTiff. The tiff file dimensions must be ordered properly (x,y,z,c,t). Don't forget that you will need the leverUtilities project (see above) on your matlab path for this to work.
debugging
a. use microsoft's visual studio code. really. it is the best option for node/electron development. install the chrome debugging extension.
-
from the debug tab (bug icon), find the launch.json (gear icon). pick from the configuration dropdown which to run. leverjs defaults to experiment window (render process). image window (render process) is also useful. electron is a two process application - a main process that manages o/s / node stuff and a render process that manages chromium (browser) window stuff.
-
from the electron app (leversc), both the image and experiment window have a menu option view/Toggle Developer Tools. This will bring up the chrome debug console. you may find error messages here. if you are having a problem, copy all the text from here and send it to andy.
b. it is possible to open the .LEVER file directly using e.g. the DB Browser sqlite viewer. Note that the .LEVER file format is likely to change significantly at any time, and use this power for debugging purposes only.
c. when running in client-server mode, to debug matlab process, edit config.js and set 'debugMatlab' to true. start the image window renderer program, pick your algorithms and select reseg all (or next). then start matlab. run matlabpollDB('\path\to\leverFile.LEVER'). Or, just run matlabPollDB and it usually finds the right LEVER file automagically (from lever.state tidbit left by CmdLoop.js).
interactive use
leverjs can be used interactively from any image analysis environment. MATLAB has the most helper code.
prerequisites,
(1) add to your path: hydra-image-processor/source/src/matlab and leverUtilities/src/matlab (2) run AddSQLiteToPath();
now, some useful tidbits:
strDB='\path\to\your\leverFile.LEVER';
[conn,CONSTANTS,segParams]=openDB(strDB);
conn is the database connection to your lever file. it is used in almost all the MATLAB entry points. segParams are the segmentation settings on your file. these need to be set first. if you want to debug your segmentation (i.e. Segment.frameSegment()) be sure segParams.minimumRadius_um is set to a scalar (not an ensemble segmentation).
% segment time t
cx=Segment.frameSegment(conn,t,CONSTANTS,segParams);
% write results into database for visualization - most useful for 3-d viewing
% be sure there are not already objects at time t in the database
Write.CreateCells(conn,cx);
security
for the client-server application, security is included at every network level, from the firewall, to the nginx reverse proxy, to auth0 (https://auth0.com) user api tokens, to programmatic access tokens using private/public key signing. more details to follow soon...the most secure route is to use the electron app for all your processing. The server will still allow viewing the data (as long as your firewall has those ports open), but editing the database will be forbidden -- a good compromise to start with.
Alternatively, to access the api functionality, you can use auth0 for use authentication. you will need to create an auth0.com account and application key (more details TBD). Alternatively, if you start the lever server with no security (node server.js --secure=false ...) you can then use your firewall to limit incoming connections on the server port to localhost only (easiest but not very secure). See auth0_config.md for more detail.
You can also generate your own keys for programmatic authentication (run node.exe leverjs\keyGen.js, see matlab+Client for examples).