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

there are two ways to run lever -- standalone or client server. it's mostly the same code either way, but there are some key differences. both use a node.js backend, with a webgl2 rendering client. the standalone uses the http://electron.atom.io framework to combine nodejs with chromium into an executable that can be run on windows/mac or linux. the client server uses nodejs for the server, combining google's v8 javascript engine with operating system support for e.g. file system access and manipulation. the client is any webgl2 compatible browser -- currently chrome (suggested), firefox or opera. note that edge and safari do not yet support webgl2 (come on Microsoft and Apple, let's get after it!)

most functionality is available from either stand-alone or client-server. the exception is importing microscope files into the lever format, and using the scriptable visualization for movie making -- both of these are only available in the stand-alone (electron) app.

there are two main entry points as well -- experiment window and image window. experiment window lists all movies in a folder tree, and allows processing multiple movies. the stand-alone experiment viewer has an import tab that will convert any microscope file format into the lever format (any format compatible with bioformats -- see http://www.openmicroscopy.org/bio-formats/).

the image window shows the images together with analysis results, with play/pause, zoom, view control, etc. the stand-alone image window has a server tab that allows starting a client/server session and also exposes scriptable control of the viewer, including getting/setting view parameters and capturing screen shots of the rendered window to a remote client like matlab or python for scriptable movie making.

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 initally it seems likely we will stick to the GPL license. Please contact Andy if you have any input or feedback on this question.

INSTALL OPTIONS

We provide stand-alone installers for Windows 10 (64 bit) and for Mac OS (High Sierra) computers. This prebuilt version provides most (but not all) functionality that would be available if installing from the source code (see below). lever.js works with unix as well, but for now requires installation from the source code.

open this link: https://leverjs.net/download/. click on the latest (windows -- use the .exe file, mac -- use the .dmg). i don't have a code signing cert yet. that is really my code above, on my server, verified by the https. so, tell your browser to just install it. NOTE on the mac the autoupdate feature requires the program be "digitally signed". I don't have a certificate to sign this code, so if you are informed of an update being available, choose "download later", navigate to the server link above, and install the updated dmg directly.

you can download sample image data from the link as well, as well as a zip file of a recent git archive (better to see "INSTALLING FROM SOURCE" below)

Finally, (sort of optionally, you really will want this) install the matlab 2019b runtime (v9.7) so analysis and image import to work: https://www.mathworks.com/products/compiler/matlab-runtime.html. If you have matlab 2019b installed (including database toolkit) you can skip this step.

INSTALLING FROM SOURCE

prerequisites

0. install node.js (I suggest the latest 'LTS' version) from https://nodejs.org

1. install python 2.7 (and make sure it's on your path!). from the node.js command prompt, type 'python' to be sure. NOTE I did not need to do this explicitly on the mac.

2. 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

3. install git lfs support from https://git-lfs.github.com/

4. from a git terminal (node.js command prompt or mac/unix terminal window), run:

 git lfs install

5. 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.

6. 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 run the electron app:

npm start

and import microscope files, or 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)

installation troubleshooting

notes

a. you will need to have matlab2019b installed, or the runtime. download the runtime from https://www.mathworks.com/products/compiler/matlab-runtime.html

b. the software works on windows, unix and mac. for unix and mac, the matlab path in cmdloop.js is hardcoded (see CmdLoop.js.getMCRpath()). for mac, the path to the nodejs binary is also hardcoded in the importer (matlab/+Import/leverImport.m) as /usr/local/bin/node. this is because matlab on mac doesn't seem to pick up the system path variable...

c. for ubuntu, you will need to 'chmod +x' the files in the leverjs/prebuilt folder. you also need to check that the matlab path in cmdloop.js (see launchMatlab()) is set correctly.

d. executing build.m in the leverjs/matlab folder is a good way to be sure you have the latest prebuilt, especially for unix where builds are not always kept up to date.

image import

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.

0. 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.

1. from the electron app, 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. 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

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);

scripting and image capture for visualization

security

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).