diff --git a/docs/methods.md b/docs/api.md similarity index 58% rename from docs/methods.md rename to docs/api.md index c8b279dc2632525bb2293f0a1a084161790fc355..7f7ef054209a05f51a9fa0b7fbbb1e6c6a4fe70d 100644 --- a/docs/methods.md +++ b/docs/api.md @@ -1,4 +1,4 @@ -# LEVERSC: Cross-Platform Scriptable Multichannel 3-D Visualization for Fluorescence Microscopy Images (Online Methods) +# LEVERSC: Cross-Platform Scriptable Multichannel 3-D Visualization for Fluorescence Microscopy Images (API Documentation) # Architecture The LEVERSC visualization tool is a [node.js](https://nodejs.org) application for visualization of multichannel 3-D volumetric data using webgl. @@ -8,179 +8,7 @@ Currently LEVERSC has plugins for ImageJ, Python and MATLAB. Additional plugins This architecture is very flexible and supports fast, cross-platform communication between any image processing environment that supports HTTP POST/GET requests. A detailed API breakdown follows, as well as example usage from Python and MATLAB. -# Usage Example -## Scripted Movie Rendering (in MATLAB) -In this section we will discuss in detail the usage of the script application programming interface ([API](#api)) for rendering high-quality presentation movies. -The full script ([```sampleVolumeMovie.m```](../src/MATLAB/sampleVolumeMovie.m)) is available in the ```src/MATLAB``` directory of the LEVERSC repository. - -### Movie setup -We begin by loading some image data, in this case from the sample .LEVER file distributed along with the LEVERSC repository. -```matlab -%% Load image (in this case from a LEVER file) -strDB='../../sampleImages/lscSampleImage.LEVER'; -[im,CONSTANTS]=leversc.loadImage(strDB); -``` - -A leversc class object must be initialized, here we initialize the leversc class with image data and metadata (metadata fields such as ```PixelPhysicalSize``` are important for correct data visualization). -```matlab -% Initialize leversc class with image and metadata -lsc=leversc(im,CONSTANTS); -``` - -A reproducible movie render should set the rendering parameters consistently at the beginning of rendering to properly visualize the data. -In this case we used the LEVERSC tool interface to interactively identify good visualization values, then used the ```/renderParams``` API call to read the current settings. -The image below shows the LEVERSC interface for selecting visualization (rendering) parameters: - - - - -The selected rendering parameters were hard-coded into our rendering script. -```matlab -%% Set up pre-selected render properties -lsc.renderParams(1).alpha = 1; -lsc.renderParams(1).dark = 0; -lsc.renderParams(1).medium = 0.78; -lsc.renderParams(1).bright = 0.96; -lsc.renderParams(1).color = [1;1;1]; -``` - -We disable the display of most UI elements -```matlab -%% Disable most UI elements -lsc.uiParams.sidebar='none'; -lsc.uiParams.clockButton='none'; -lsc.uiParams.webToolbar='none'; -``` - -We reset the view parameters to defaults for the start of the movie: -```matlab -%% Reset view parameters (also set background to black) -lsc.viewParams.clipMode = 0; -lsc.viewParams.worldRot = reshape([1,0,0,0; 0,1,0,0; 0,0,1,0; 0,0,0,1], 16,1); -lsc.viewParams.zoom = 0; -lsc.viewParams.bgColor = [0,0,0]; -``` - -The first step in this movie is to apply a quick animated zoom to fill the display with the actual data in the volume, capturing frames for each zoom level. -Since our movie will run at 10 frames per second (fps) we interpolate our zoom over 10 frames (a 1 second zoom): -```matlab -%% Quick zoom from 0 to 0.4 (1 sec = 10 frames) -zlevels = linspace(0,0.4, 10); -for i=1:length(zlevels) - lsc.viewParams.zoom=zlevels(i); - - imCap = get_rendered_frame(lsc); - if ( bPreview ) - imagesc(imCap); - axis image; - drawnow(); - else - writeVideo(vidWrite,imCap); - end -end -``` - -Next we apply a 5 second (50 frame) rotation of 180 degrees about the y-axis: -```matlab -%% Rotate halfway around in 5sec -angles = linspace(0,180,50); -for i=2:length(angles) - ry=[cosd(angles(i)), 0, sind(angles(i)),0; - 0,1,0,0; - -sind(angles(i)),0,cosd(angles(i)),0; - 0,0,0,1]; - - worldRot=ry; - lsc.viewParams.worldRot=worldRot(:); - - imCap = get_rendered_frame(lsc); - if ( bPreview ) - imagesc(imCap); - axis image; - drawnow(); - else - writeVideo(vidWrite,imCap); - end -end -``` - -Next we move the sampling plane to the edge of the volume and turn on planar clipping. -Then we animate moving the plane to just a little back from the volume center. -The plane animation is 2 seconds (20 frames) long: -```matlab -%% Put sample plane at the back of the volume and set to planar clipping mode, -%% then animate plane movement into just back from center -planeZs = linspace(85,50, 20); -lsc.viewParams.planeCenter(3) = planeZs(1); -lsc.viewParams.clipMode = 1; % Plane-clipping mode -for i=1:length(planeZs) - lsc.viewParams.planeCenter(3) = planeZs(i); - - imCap = get_rendered_frame(lsc); - if ( bPreview ) - imagesc(imCap); - axis image; - drawnow(); - else - writeVideo(vidWrite,imCap); - end -end -``` - -We apply another 180 degree rotation to rotate the volume the rest of the way back to the starting view. -This time we show matrix multiplication for the world rotation matrix by a delta rotation matrix: -```matlab -%% Rotate the rest of the way around with plane clipping on (5sec) -% This time we use a "delta" rotation matrix to show how matrix -% products can be used -frameRots = 50; -angleDelta = 180 / frameRots; -deltaRY = [cosd(angleDelta), 0, sind(angleDelta),0; - 0,1,0,0; - -sind(angleDelta),0,cosd(angleDelta),0; - 0,0,0,1]; -worldRot = reshape(lsc.viewParams.worldRot, 4,4); -for i=1:frameRots - worldRot = deltaRY * worldRot; - lsc.viewParams.worldRot = worldRot(:); - - imCap = get_rendered_frame(lsc); - if ( bPreview ) - imagesc(imCap); - axis image; - drawnow(); - else - writeVideo(vidWrite,imCap); - end -end -``` - -As a final animation, we change the plane clipping mode to slice sampling, and animate moving out of the volume towards the camera: -```matlab -%% Change to slice clipping mode and pull plane back toward camera -startZ = lsc.viewParams.planeCenter(3); -planeZs = linspace(startZ,1,20); -lsc.viewParams.clipMode = 2; % Slice-clipping mode -for i=1:length(planeZs) - lsc.viewParams.planeCenter(3) = planeZs(i); - - imCap = get_rendered_frame(lsc); - if ( bPreview ) - imagesc(imCap); - axis image; - drawnow(); - else - writeVideo(vidWrite,imCap); - end -end -``` -If run with the ```bPreview``` flag set to false, this will generate ```lscSampleMovie.mp4```. -**NOTE:** The LEVERSC window size will determine the resolution of the video produced, so it is important to set the window size appropriately before running the video script. - -Using the example shown here, as well as the full ```viewParams``` and ```renderParams``` API calls, complex camera and movie effects can be built through interpolation of multiple parameters at each frame. - - -# API +# Application Programming Interface (API) ## Ports LEVERSC *Figure* windows are represented by port bindings, beginning at port 3001 for figure 1 and port 3002 for figure 2, etc. diff --git a/docs/plugin_example.md b/docs/plugin_example.md new file mode 100644 index 0000000000000000000000000000000000000000..9921c0f0278abe06d08020c76c0483795d9633e9 --- /dev/null +++ b/docs/plugin_example.md @@ -0,0 +1,5 @@ +# LEVERSC: Cross-Platform Scriptable Multichannel 3-D Visualization for Fluorescence Microscopy Images + +# Developing a LEVERSC Plugin +This section provides a concrete example of implementing a very basic Python module to send multichannel 3-D NumPy array data to the LEVERSC tool via the HTTP request API. Though this is an introductory example, very similar code is implemented in the [LEVERSC Python interface](../src/Python/leversc.py). + diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000000000000000000000000000000000000..bd2af98feef26d86976b1d568fab1f421d5992a0 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,171 @@ +# LEVERSC: Cross-Platform Scriptable Multichannel 3-D Visualization for Fluorescence Microscopy Images (Usage Example) +# Usage Example +## Scripted Movie Rendering (in MATLAB) +In this section we will discuss in detail the usage of the script application programming interface ([API](#api)) for rendering high-quality presentation movies. +The full script ([```sampleVolumeMovie.m```](../src/MATLAB/sampleVolumeMovie.m)) is available in the ```src/MATLAB``` directory of the LEVERSC repository. + +### Movie setup +We begin by loading some image data, in this case from the sample .LEVER file distributed along with the LEVERSC repository. +```matlab +%% Load image (in this case from a LEVER file) +strDB='../../sampleImages/lscSampleImage.LEVER'; +[im,CONSTANTS]=leversc.loadImage(strDB); +``` + +A leversc class object must be initialized, here we initialize the leversc class with image data and metadata (metadata fields such as ```PixelPhysicalSize``` are important for correct data visualization). +```matlab +% Initialize leversc class with image and metadata +lsc=leversc(im,CONSTANTS); +``` + +A reproducible movie render should set the rendering parameters consistently at the beginning of rendering to properly visualize the data. +In this case we used the LEVERSC tool interface to interactively identify good visualization values, then used the ```/renderParams``` API call to read the current settings. +The image below shows the LEVERSC interface for selecting visualization (rendering) parameters: + + + + +The selected rendering parameters were hard-coded into our rendering script. +```matlab +%% Set up pre-selected render properties +lsc.renderParams(1).alpha = 1; +lsc.renderParams(1).dark = 0; +lsc.renderParams(1).medium = 0.78; +lsc.renderParams(1).bright = 0.96; +lsc.renderParams(1).color = [1;1;1]; +``` + +We disable the display of most UI elements +```matlab +%% Disable most UI elements +lsc.uiParams.sidebar='none'; +lsc.uiParams.clockButton='none'; +lsc.uiParams.webToolbar='none'; +``` + +We reset the view parameters to defaults for the start of the movie: +```matlab +%% Reset view parameters (also set background to black) +lsc.viewParams.clipMode = 0; +lsc.viewParams.worldRot = reshape([1,0,0,0; 0,1,0,0; 0,0,1,0; 0,0,0,1], 16,1); +lsc.viewParams.zoom = 0; +lsc.viewParams.bgColor = [0,0,0]; +``` + +The first step in this movie is to apply a quick animated zoom to fill the display with the actual data in the volume, capturing frames for each zoom level. +Since our movie will run at 10 frames per second (fps) we interpolate our zoom over 10 frames (a 1 second zoom): +```matlab +%% Quick zoom from 0 to 0.4 (1 sec = 10 frames) +zlevels = linspace(0,0.4, 10); +for i=1:length(zlevels) + lsc.viewParams.zoom=zlevels(i); + + imCap = get_rendered_frame(lsc); + if ( bPreview ) + imagesc(imCap); + axis image; + drawnow(); + else + writeVideo(vidWrite,imCap); + end +end +``` + +Next we apply a 5 second (50 frame) rotation of 180 degrees about the y-axis: +```matlab +%% Rotate halfway around in 5sec +angles = linspace(0,180,50); +for i=2:length(angles) + ry=[cosd(angles(i)), 0, sind(angles(i)),0; + 0,1,0,0; + -sind(angles(i)),0,cosd(angles(i)),0; + 0,0,0,1]; + + worldRot=ry; + lsc.viewParams.worldRot=worldRot(:); + + imCap = get_rendered_frame(lsc); + if ( bPreview ) + imagesc(imCap); + axis image; + drawnow(); + else + writeVideo(vidWrite,imCap); + end +end +``` + +Next we move the sampling plane to the edge of the volume and turn on planar clipping. +Then we animate moving the plane to just a little back from the volume center. +The plane animation is 2 seconds (20 frames) long: +```matlab +%% Put sample plane at the back of the volume and set to planar clipping mode, +%% then animate plane movement into just back from center +planeZs = linspace(85,50, 20); +lsc.viewParams.planeCenter(3) = planeZs(1); +lsc.viewParams.clipMode = 1; % Plane-clipping mode +for i=1:length(planeZs) + lsc.viewParams.planeCenter(3) = planeZs(i); + + imCap = get_rendered_frame(lsc); + if ( bPreview ) + imagesc(imCap); + axis image; + drawnow(); + else + writeVideo(vidWrite,imCap); + end +end +``` + +We apply another 180 degree rotation to rotate the volume the rest of the way back to the starting view. +This time we show matrix multiplication for the world rotation matrix by a delta rotation matrix: +```matlab +%% Rotate the rest of the way around with plane clipping on (5sec) +% This time we use a "delta" rotation matrix to show how matrix +% products can be used +frameRots = 50; +angleDelta = 180 / frameRots; +deltaRY = [cosd(angleDelta), 0, sind(angleDelta),0; + 0,1,0,0; + -sind(angleDelta),0,cosd(angleDelta),0; + 0,0,0,1]; +worldRot = reshape(lsc.viewParams.worldRot, 4,4); +for i=1:frameRots + worldRot = deltaRY * worldRot; + lsc.viewParams.worldRot = worldRot(:); + + imCap = get_rendered_frame(lsc); + if ( bPreview ) + imagesc(imCap); + axis image; + drawnow(); + else + writeVideo(vidWrite,imCap); + end +end +``` + +As a final animation, we change the plane clipping mode to slice sampling, and animate moving out of the volume towards the camera: +```matlab +%% Change to slice clipping mode and pull plane back toward camera +startZ = lsc.viewParams.planeCenter(3); +planeZs = linspace(startZ,1,20); +lsc.viewParams.clipMode = 2; % Slice-clipping mode +for i=1:length(planeZs) + lsc.viewParams.planeCenter(3) = planeZs(i); + + imCap = get_rendered_frame(lsc); + if ( bPreview ) + imagesc(imCap); + axis image; + drawnow(); + else + writeVideo(vidWrite,imCap); + end +end +``` +If run with the ```bPreview``` flag set to false, this will generate ```lscSampleMovie.mp4```. +**NOTE:** The LEVERSC window size will determine the resolution of the video produced, so it is important to set the window size appropriately before running the video script. + +Using the example shown here, as well as the full ```viewParams``` and ```renderParams``` API calls, complex camera and movie effects can be built through interpolation of multiple parameters at each frame. diff --git a/readme.md b/readme.md index 1fb94ea0410ec94892cf7ef8b2daeab4d32ee5f7..2039e2b1db7b5e512ac5d23623a65bdc3bbb4e04 100644 --- a/readme.md +++ b/readme.md @@ -68,6 +68,8 @@ debug output. ## Further Details -Details of the LEVERSC tool architecture and API can be found in the [methods](docs/methods.md "LEVERSC online methods") section. The source code for LEVERSC integrations are available in this repository ([ImageJ plugin](src/ImageJ "ImageJ plugin source code"), [Python module](src/Python "Python module source code"), [MATLAB class](src/MATLAB "MATLAB class and helper source code")). +Details of the LEVERSC tool architecture and API can be found in the online [API documentation](docs/api.md "LEVERSC API documentation"). A detailed usage example is available [here](docs/usage.md "LEVERSC usage example"), and a step-by-step guide for implementing a plugin to communicate with LEVERSC through the API is provided [here](docs/plugin_example.md "LEVERSC plugin guide"). + +The source code for LEVERSC integrations are available in this repository ([ImageJ plugin](src/ImageJ "ImageJ plugin source code"), [Python module](src/Python "Python module source code"), [MATLAB class](src/MATLAB "MATLAB class and helper source code")). Additionally, the node.js and webgl source code for the LEVERJS/LEVERSC tool, as well as build instructions are available in the main [leverjs repository](https://git-bioimage.coe.drexel.edu/opensource/leverjs "LEVERJS source code repository").