The LEVERSC visualization tool is a [node.js](https://nodejs.org) application for visualization of multichannel 3-D volumetric data using webgl.
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
...
@@ -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.
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.
A detailed API breakdown follows, as well as example usage from Python and MATLAB.
# Usage Example
# Application Programming Interface (API)
## 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 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);
fori=1:length(zlevels)
lsc.viewParams.zoom=zlevels(i);
imCap=get_rendered_frame(lsc);
if(bPreview)
imagesc(imCap);
axisimage;
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);
fori=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);
axisimage;
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
fori=1:length(planeZs)
lsc.viewParams.planeCenter(3)=planeZs(i);
imCap=get_rendered_frame(lsc);
if(bPreview)
imagesc(imCap);
axisimage;
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);
fori=1:frameRots
worldRot=deltaRY*worldRot;
lsc.viewParams.worldRot=worldRot(:);
imCap=get_rendered_frame(lsc);
if(bPreview)
imagesc(imCap);
axisimage;
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
fori=1:length(planeZs)
lsc.viewParams.planeCenter(3)=planeZs(i);
imCap=get_rendered_frame(lsc);
if(bPreview)
imagesc(imCap);
axisimage;
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
## Ports
## Ports
LEVERSC *Figure* windows are represented by port bindings, beginning at port 3001 for figure 1 and port 3002 for figure 2, etc.
LEVERSC *Figure* windows are represented by port bindings, beginning at port 3001 for figure 1 and port 3002 for figure 2, etc.
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).
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 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);
fori=1:length(zlevels)
lsc.viewParams.zoom=zlevels(i);
imCap=get_rendered_frame(lsc);
if(bPreview)
imagesc(imCap);
axisimage;
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);
fori=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);
axisimage;
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
fori=1:length(planeZs)
lsc.viewParams.planeCenter(3)=planeZs(i);
imCap=get_rendered_frame(lsc);
if(bPreview)
imagesc(imCap);
axisimage;
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);
fori=1:frameRots
worldRot=deltaRY*worldRot;
lsc.viewParams.worldRot=worldRot(:);
imCap=get_rendered_frame(lsc);
if(bPreview)
imagesc(imCap);
axisimage;
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
fori=1:length(planeZs)
lsc.viewParams.planeCenter(3)=planeZs(i);
imCap=get_rendered_frame(lsc);
if(bPreview)
imagesc(imCap);
axisimage;
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.
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").
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").
