TissueLens
Repository source: TissueLens
Description¶
Here a "magnifying lens" or "window" effect is generated, allowing users to peek inside a 3D medical dataset—such as a human head CT or MRI scan—by cutting a clean hole into the outer layer (the skin) to reveal the underlying structures (like the brain or bone) inside a specific region.
This example uses two vtkClipDataSet filters to achieve a "tissue lens" effect. First, a vtkSphere implicit function is used to clip a spherical hole in the isosurface extracted with vtkFlyingEdges3D or vtkMarchingCubes. Then a geometric vtkSphereSource samples the original volume data using a vtkProbeFilter. vtkClipDataSet uses the resulting scalar point data to clip the sphere surface with the isosurface value.
Usage
TissueLens FullHead.mhd
Note
The skin color was selected from Table 7 in Improvement of Haar Feature Based Face Detection in OpenCV Incorporating Human Skin Color Characteristic
Info
The example uses src/Testing/Data/FullHead.mhd which references src/Testing/Data/FullHead.raw.gz.
Other languages
See (Python), (PythonicAPI)
Question
If you have a question about this example, please use the VTK Discourse Forum
Code¶
TissueLens.cxx
#include <vtkActor.h>
#include <vtkCamera.h>
#include <vtkCameraOrientationRepresentation.h>
#include <vtkCameraOrientationWidget.h>
#include <vtkClipDataSet.h>
#include <vtkDataSetMapper.h>
#include <vtkFlyingEdges3D.h>
#include <vtkInteractorStyleSwitch.h>
#include <vtkLookupTable.h>
#include <vtkMarchingCubes.h>
#include <vtkMatrix4x4.h>
#include <vtkMetaImageReader.h>
#include <vtkNamedColors.h>
#include <vtkNew.h>
#include <vtkPolyDataMapper.h>
#include <vtkProbeFilter.h>
#include <vtkProperty.h>
#include <vtkRenderWindow.h>
#include <vtkRenderWindowInteractor.h>
#include <vtkRenderer.h>
#include <vtkSphere.h>
#include <vtkSphereSource.h>
#include <vtkStringFormatter.h>
#include <vtkTransform.h>
#include <vtkUnstructuredGrid.h>
#include <vtk_cli11.h>
#include <vtk_fmt.h>
// clang-format off
#include VTK_FMT(fmt/format.h)
// clang-format on
#include <array>
#include <filesystem>
namespace fs = std::filesystem;
namespace {
class Permute
{
// clang-format off
/*
* These transformations permute image and other geometric data to maintain
* proper orientation regardless of the acquisition order. After applying
* these transforms with vtkTransformFilter, a view up of 0, -1, 0 will
* result in the body part facing the viewer.
*
* NOTE: Some transformations have a -1 scale factor for one of the components.
* To ensure proper polygon orientation and normal direction,
* you must apply the vtkPolyDataNormals filter.
*
* Naming (the nomenclature is medical):
* si - superior to inferior (top to bottom)
* is - inferior to superior (bottom to top)
* ap - anterior to posterior (front to back)
* pa - posterior to anterior (back to front)
* lr - left to right
* rl - right to left
*
*/
// clang-format on
public:
/**
* Generate the transforms corresponding to the slice order.
*/
Permute()
{
GenerateTransforms();
}
virtual ~Permute() = default;
public:
/**
* Returns the vtkTransform corresponding to the permutation.
*
* @param permutation: The permutation.
* @return The vtkTransform corresponding to the permutation.
*/
vtkSmartPointer<vtkTransform> GetTransform(std::string const& permutation);
/**
* Print the homogenous matrix corresponding to the permutation.
*
* @param order: The permutation.
*/
void PrintTransform(std::string const& permutation);
/**
* Print all the homogenous matrices corresponding to the permutations.
*
*/
void PrintAlltransforms();
private:
/**
* @brief Generate the transforms and collect them into a map.
*
*/
void GenerateTransforms();
private:
std::map<std::string, vtkSmartPointer<vtkTransform>> transform;
// Used to generate the the homogenous matrices corresponding to the
// permutations.
std::array<double, 16> si_arr{1, 0, 0, 0, 0, 0, 1, 0,
0, -1, 0, 0, 0, 0, 0, 1};
std::array<double, 16> is_arr{1, 0, 0, 0, 0, 0, -1, 0,
0, -1, 0, 0, 0, 0, 0, 1};
std::array<double, 16> lr_arr{0, 0, -1, 0, 0, -1, 0, 0,
1, 0, 0, 0, 0, 0, 0, 1};
std::array<double, 16> rl_arr{0, 0, 1, 0, 0, -1, 0, 0,
1, 0, 0, 0, 0, 0, 0, 1};
std::array<double, 16> hf_arr{-1, 0, 0, 0, 0, 1, 0, 0,
0, 0, -1, 0, 0, 0, 0, 1};
// Used to print out the homogenous matrices in the order
// entered into the transform map.
std::vector<std::string> sort_order{};
};
class COWPlacement
{
public:
COWPlacement()
{
MakeLabelColor();
}
virtual ~COWPlacement() = default;
public:
/**
* @brief Make a camera orientation widget for a given renderer.
* * position has these values
* 0: LowerLeft,
* 1: UpperLeft,
* 2: LowerRight,
* 3: UpperRight - the default
*
* @param ren The renderer.
* @param lcKey The key specifying the desired labels and colors for the axes.
* @param position Where to position the camera orientation widget.
* @return The camera orientation widget.
*/
vtkNew<vtkCameraOrientationWidget>
MakeCOW(vtkRenderer* ren, std::string lcKey = "XYZ", int const& position = 3);
private:
typedef std::map<std::string, std::string> TAP;
typedef std::map<std::string, TAP> TAPS;
std::map<std::string, std::pair<TAP, TAP>> labelColor;
/**
* @brief Gather the defined axes labels and colors into a map.
* */
void MakeLabelColor();
};
} // namespace
int main(int argc, char* argv[])
{
CLI::App app{"Generate a \"magnifying lens\" or \"window\" effect,"
" allowing users to peek inside a 3D medical dataset."};
// Define options
std::string fileName;
app.add_option("fileName", fileName,
"The path to the data file e.g. FullHead.mhd.")
->required()
->check(CLI::ExistingFile);
bool flyingEdges = true;
app.add_flag("-m{false},!-n", flyingEdges,
"Use flying edges by default, marching cubes if set.");
CLI11_PARSE(app, argc, argv);
vtkNew<vtkNamedColors> colors;
std::array<unsigned char, 4> skinColor{{240, 184, 160, 255}};
colors->SetColor("SkinColor", skinColor.data());
std::array<unsigned char, 4> backColor{{255, 229, 200, 255}};
colors->SetColor("BackfaceColor", backColor.data());
std::array<unsigned char, 4> bkg{{51, 77, 102, 255}};
colors->SetColor("BkgColor", bkg.data());
// Create the renderer, the render window, and the interactor. The
// renderer draws into the render window, the interactor enables
// mouse- and keyboard-based interaction with the data within the
// render window.
//
vtkNew<vtkRenderer> ren;
vtkNew<vtkRenderWindow> renWin;
// Set a background color for the renderer and set the size of the
// render window (expressed in pixels).
ren->SetBackground(colors->GetColor3d("BkgColor").GetData());
renWin->SetSize(640, 480);
auto appFn = fs::path((app.get_name())).stem().string();
renWin->SetWindowName(appFn.c_str());
renWin->AddRenderer(ren);
vtkNew<vtkRenderWindowInteractor> iren;
iren->SetRenderWindow(renWin);
auto is = vtkInteractorStyleSwitch::SafeDownCast(iren->GetInteractorStyle());
if (is)
{
is->SetCurrentStyleToTrackballCamera();
}
// Read the volume data.
vtkNew<vtkMetaImageReader> reader;
reader->SetFileName(argv[1]);
reader->Update();
// An isosurface, or contour value of 500 is known to correspond to the
// skin of the patient.
#ifdef USE_FLYING_EDGES
vtkNew<vtkFlyingEdges3D> skinExtractor;
#else
vtkNew<vtkMarchingCubes> skinExtractor;
#endif
skinExtractor->SetInputConnection(reader->GetOutputPort());
skinExtractor->SetValue(0, 500);
std::array<double, 3> clipCenter{-70, 60, -10};
// Define a spherical clip function to clip the isosurface.
vtkNew<vtkSphere> clipFunction;
clipFunction->SetRadius(50);
clipFunction->SetCenter(clipCenter.data());
// Clip the isosurface with a sphere.
vtkNew<vtkClipDataSet> skinClip;
skinClip->SetInputConnection(skinExtractor->GetOutputPort());
skinClip->SetClipFunction(clipFunction);
skinClip->SetValue(0);
skinClip->GenerateClipScalarsOn();
skinClip->Update();
vtkNew<vtkDataSetMapper> skinMapper;
skinMapper->SetInputConnection(skinClip->GetOutputPort());
skinMapper->ScalarVisibilityOff();
vtkNew<vtkProperty> skinProp;
skinProp->SetDiffuseColor(colors->GetColor3d("SkinColor").GetData());
vtkNew<vtkProperty> backProp;
backProp->SetDiffuseColor(colors->GetColor3d("BackfaceColor").GetData());
vtkNew<vtkActor> skin;
skin->SetMapper(skinMapper);
skin->SetProperty(skinProp);
skin->SetBackfaceProperty(backProp);
// Define a model for the "lens". Its geometry matches the implicit
// sphere used to clip the isosurface.
vtkNew<vtkSphereSource> lensModel;
lensModel->SetRadius(50);
lensModel->SetCenter(clipCenter.data());
lensModel->SetPhiResolution(201);
lensModel->SetThetaResolution(101);
// Sample the input volume with the lens model geometry.
vtkNew<vtkProbeFilter> lensProbe;
lensProbe->SetInputConnection(lensModel->GetOutputPort());
lensProbe->SetSourceConnection(reader->GetOutputPort());
// Clip the lens data with the isosurface value.
vtkNew<vtkClipDataSet> lensClip;
lensClip->SetInputConnection(lensProbe->GetOutputPort());
lensClip->SetValue(500);
lensClip->GenerateClipScalarsOff();
lensClip->Update();
// Define a suitable grayscale lut.
vtkNew<vtkLookupTable> bwLut;
bwLut->SetTableRange(0, 2048);
bwLut->SetSaturationRange(0, 0);
bwLut->SetHueRange(0, 0);
bwLut->SetValueRange(0.2, 1);
bwLut->Build();
vtkNew<vtkDataSetMapper> lensMapper;
lensMapper->SetInputConnection(lensClip->GetOutputPort());
lensMapper->SetScalarRange(lensClip->GetOutput()->GetScalarRange());
lensMapper->SetLookupTable(bwLut);
vtkNew<vtkActor> lens;
lens->SetMapper(lensMapper);
// It is convenient to create an initial view of the data.
vtkNew<vtkCamera> camera;
camera->Azimuth(30.0);
camera->Elevation(30.0);
// This transform positions the actors correctly.
// The face of the head will now face the observer.
auto permute = Permute();
auto lsa = permute.GetTransform("si");
lens->SetUserTransform(lsa);
skin->SetUserTransform(lsa);
// Actors are added to the renderer. An initial camera view is created.
// The Dolly() method moves the camera towards the FocalPoint,
// thereby enlarging the image.
ren->AddActor(lens);
ren->AddActor(skin);
ren->SetActiveCamera(camera);
ren->ResetCamera();
camera->Dolly(1.5);
// Note that when camera movement occurs (as it does in the Dolly()
// method), the clipping planes often need adjusting. Clipping planes
// consist of two planes: near and far along the view direction. The
// near plane clips out objects in front of the plane; the far plane
// clips out objects behind the plane. This way only what is drawn
// between the planes is actually rendered.
ren->ResetCameraClippingRange();
// Important: The interactor must be set prior to enabling the widget.
auto cowp = COWPlacement();
auto cow = cowp.MakeCOW(ren);
// Enable the widget.
cow->On();
auto category = "LSA";
auto cow1 = cowp.MakeCOW(ren, category, 1);
// Enable the widget.
cow1->On();
// Initialize the event loop and then start it.
renWin->Render();
iren->Initialize();
iren->Start();
return EXIT_SUCCESS;
}
namespace {
void Permute::GenerateTransforms()
{
vtkNew<vtkMatrix4x4> si_mat;
si_mat->SetData(this->si_arr.data());
vtkNew<vtkMatrix4x4> is_mat;
is_mat->SetData(this->is_arr.data());
vtkNew<vtkMatrix4x4> lr_mat;
lr_mat->SetData(this->lr_arr.data());
vtkNew<vtkMatrix4x4> rl_mat;
rl_mat->SetData(this->rl_arr.data());
// The previous transforms assume radiological views of the slices
// (viewed from the feet).
// Other modalities such as physical sectioning may view from the head.
// The following transforms modify the original with a 180° rotation
// about the y-axis.
vtkNew<vtkMatrix4x4> hf_mat;
hf_mat->SetData(this->hf_arr.data());
vtkNew<vtkTransform> si_trans;
si_trans->SetMatrix(si_mat);
this->transform["si"] = si_trans;
this->sort_order.push_back("si");
vtkNew<vtkTransform> is_trans;
is_trans->SetMatrix(is_mat);
this->transform["is"] = is_trans;
this->sort_order.push_back("is");
vtkNew<vtkTransform> ap_trans;
ap_trans->Scale(1, -1, 1);
this->transform["ap"] = ap_trans;
this->sort_order.push_back("ap");
vtkNew<vtkTransform> pa_trans;
pa_trans->Scale(1, -1, -1);
this->transform["pa"] = pa_trans;
this->sort_order.push_back("pa");
vtkNew<vtkTransform> lr_trans;
lr_trans->SetMatrix(lr_mat);
this->transform["lr"] = lr_trans;
this->sort_order.push_back("lr");
vtkNew<vtkTransform> rl_trans;
lr_trans->SetMatrix(rl_mat);
this->transform["rl"] = rl_trans;
this->sort_order.push_back("rl");
vtkNew<vtkTransform> hf_trans;
hf_trans->SetMatrix(hf_mat);
this->transform["hf"] = hf_trans;
this->sort_order.push_back("hf");
vtkNew<vtkTransform> hf_si_trans;
hf_si_trans->SetMatrix(hf_mat);
hf_si_trans->Concatenate(si_mat);
this->transform["hfsi"] = hf_si_trans;
this->sort_order.push_back("hfsi");
vtkNew<vtkTransform> hf_is_trans;
hf_is_trans->SetMatrix(hf_mat);
hf_is_trans->Concatenate(is_mat);
this->transform["hfis"] = hf_is_trans;
this->sort_order.push_back("hfis");
vtkNew<vtkTransform> hf_ap_trans;
hf_ap_trans->SetMatrix(hf_mat);
hf_ap_trans->Scale(1, -1, 1);
this->transform["hfap"] = hf_ap_trans;
this->sort_order.push_back("hfap");
vtkNew<vtkTransform> hf_pa_trans;
hf_pa_trans->SetMatrix(hf_mat);
hf_pa_trans->Scale(1, -1, -1);
this->transform["hfpa"] = hf_pa_trans;
this->sort_order.push_back("hfpa");
vtkNew<vtkTransform> hf_lr_trans;
hf_lr_trans->SetMatrix(hf_mat);
hf_lr_trans->Concatenate(lr_mat);
this->transform["hflr"] = hf_lr_trans;
this->sort_order.push_back("hflr");
vtkNew<vtkTransform> hf_rl_trans;
hf_rl_trans->SetMatrix(hf_mat);
hf_rl_trans->Concatenate(rl_mat);
this->transform["hfrl"] = hf_rl_trans;
this->sort_order.push_back("hfrl");
// Identity
this->transform["I"] = vtkNew<vtkTransform>();
this->sort_order.push_back("I");
// Zero
vtkNew<vtkTransform> z_trans;
z_trans->Scale(0, 0, 0);
this->transform["Z"] = z_trans;
this->sort_order.push_back("Z");
}
void Permute::PrintTransform(std::string const& permutation)
{
auto m = this->transform[permutation]->GetMatrix();
vtk::println(permutation);
for (int i = 0; i < 4; ++i)
{
for (int j = 0; j < 4; ++j)
{
if (j < 3)
{
vtk::print("{:>6.2g}", m->GetElement(i, j));
}
else
{
vtk::println("{:>6.2g}", m->GetElement(i, j));
}
}
}
}
void Permute::PrintAlltransforms()
{
for (auto const& k : this->sort_order)
{
PrintTransform(k);
}
}
vtkSmartPointer<vtkTransform>
Permute::GetTransform(std::string const& permutation)
{
return this->transform[permutation];
}
void COWPlacement::MakeLabelColor()
{
vtkNew<vtkNamedColors> nc;
// Define the axes labels and colors.
// The three digit key refers to the positive X,Y,Z axes.
// clang-format off
TAPS labels {
// Labels are: Anterior, Posterior, Dorsal, Ventral, Left, Right
{"ADL",{{"+X", "A"}, {"+Y", "D"}, {"+Z", "L"}, {"-X", "P"}, {"-Y", "V"}, {"-Z", "R"}}},
{"ALV",{{"+X", "A"}, {"+Y", "L"}, {"+Z", "V"}, {"-X", "P"}, {"-Y", "R"}, {"-Z", "D"}}},
{"ADR",{{"+X", "A"}, {"+Y", "D"}, {"+Z", "R"}, {"-X", "P"}, {"-Y", "V"}, {"-Z", "L"}}},
{"ARV",{{"+X", "A"}, {"+Y", "R"}, {"+Z", "V"}, {"-X", "P"}, {"-Y", "L"}, {"-Z", "D"}}},
{"PDL",{{"+X", "P"}, {"+Y", "D"}, {"+Z", "L"}, {"-X", "A"}, {"-Y", "V"}, {"-Z", "R"}}},
// Labels are: Left, Right, Superior, Inferior, Anterior, Posterior
{"LAS",{{"+X", "L"}, {"+Y", "A"}, {"+Z", "S"}, {"-X", "R"}, {"-Y", "P"}, {"-Z", "I"}}},
{"LPA",{{"+X", "L"}, {"+Y", "P"}, {"+Z", "A"}, {"-X", "R"}, {"-Y", "A"}, {"-Z", "S"}}},
{"LPS",{{"+X", "L"}, {"+Y", "P"}, {"+Z", "S"}, {"-X", "R"}, {"-Y", "A"}, {"-Z", "I"}}},
{"LSA",{{"+X", "L"}, {"+Y", "S"}, {"+Z", "A"}, {"-X", "R"}, {"-Y", "I"}, {"-Z", "A"}}},
{"RAP",{{"+X", "R"}, {"+Y", "A"}, {"+Z", "P"}, {"-X", "L"}, {"-Y", "I"}, {"-Z", "S"}}},
{"RAS",{{"+X", "R"}, {"+Y", "A"}, {"+Z", "S"}, {"-X", "L"}, {"-Y", "P"}, {"-Z", "I"}}},
{"RPS",{{"+X", "R"}, {"+Y", "P"}, {"+Z", "S"}, {"-X", "L"}, {"-Y", "A"}, {"-Z", "I"}}},
{"RSP",{{"+X", "R"}, {"+Y", "S"}, {"+Z", "P"}, {"-X", "L"}, {"-Y", "I"}, {"-Z", "A"}}},
{"SAL",{{"+X", "S"}, {"+Y", "A"}, {"+Z", "L"}, {"-X", "I"}, {"-Y", "P"}, {"-Z", "R"}}},
// Default labels.
{"XYZ", {}},
};
// Label colors.
TAP c1{
{"+X", "IndianRed"},{"-X", "FireBrick"},
{"+Y", "LimeGreen"},{"-Y", "DarkGreen"},
{"+Z", "SkyBlue"}, {"-Z", "DeepSkyBlue"}
};
TAPS colors {
{"ADL", c1},
{"ALV", c1},
{"ADR", c1},
{"ARV", c1},
{"PDL", c1},
// Default colors.
{"LAS", {}},
{"LPS", {}},
{"LPA", {}},
{"LSA", {}},
{"RAP", {}},
{"RAS", {}},
{"RPS", {}},
{"RSP", {}},
{"SAL", {}},
// The default.
{"XYZ", {}},
};
// clang-format on
// Gather the defined axes labels and colors into a map.
// The keys must be the same in the labels and colors variables.
std::set<std::string> labelKeys;
for (auto&& label : labels)
{
labelKeys.insert(label.first);
}
std::set<std::string> colorKeys;
for (auto&& label : colors)
{
colorKeys.insert(label.first);
}
std::vector<std::string> commonKeys;
std::set_intersection(labelKeys.begin(), labelKeys.end(), colorKeys.begin(),
colorKeys.end(), std::back_inserter(commonKeys));
for (auto&& k : commonKeys)
{
this->labelColor[k] = {labels[k], colors[k]};
}
};
vtkNew<vtkCameraOrientationWidget>
COWPlacement::MakeCOW(vtkRenderer* ren, std::string lcKey, int const& position)
{
std::set<std::string> keys;
for (auto&& label : this->labelColor)
{
keys.insert(label.first);
}
auto it = keys.find(lcKey);
if (it == keys.end())
{
std::string res =
"Invalid key for axes labels and colors.\nValid keys are: ";
for (const auto& [key, value] : this->labelColor)
{
res += fmt::format("{:s}, ", key);
}
if (res.length() >= 2)
{
auto pos = res.length() - 2;
res.replace(pos, 2, "");
}
res += "\nUsing the key: XYZ";
vtk::println("{:}", res);
lcKey = "XYZ";
}
auto lc = this->labelColor[lcKey];
vtkNew<vtkCameraOrientationRepresentation> rep;
switch (position)
{
case 0:
rep->AnchorToLowerLeft();
break;
case 1:
rep->AnchorToUpperLeft();
break;
case 2:
rep->AnchorToLowerRight();
break;
default:
rep->AnchorToUpperRight();
}
if (!lc.first.empty())
{
rep->SetXPlusLabelText(lc.first["+X"]);
rep->SetXMinusLabelText(lc.first["-X"]);
rep->SetYPlusLabelText(lc.first["+Y"]);
rep->SetYMinusLabelText(lc.first["-Y"]);
rep->SetZPlusLabelText(lc.first["+Z"]);
rep->SetZMinusLabelText(lc.first["-Z"]);
}
if (!lc.second.empty())
{
vtkNew<vtkNamedColors> colors;
rep->SetXAxisColor(colors->GetColor3d(lc.second["+X"]).GetData());
rep->SetYAxisColor(colors->GetColor3d(lc.second["+Y"]).GetData());
rep->SetZAxisColor(colors->GetColor3d(lc.second["+Z"]).GetData());
}
vtkNew<vtkCameraOrientationWidget> cow;
cow->SetParentRenderer(ren);
cow->SetRepresentation(rep);
cow->Off();
return cow;
}
} // namespace
CMakeLists.txt¶
cmake_minimum_required(VERSION 3.12 FATAL_ERROR)
project(TissueLens)
find_package(VTK COMPONENTS
CommonColor
CommonCore
CommonDataModel
FiltersCore
FiltersGeneral
FiltersSources
IOImage
InteractionStyle
RenderingContextOpenGL2
RenderingCore
RenderingFreeType
RenderingGL2PSOpenGL2
RenderingOpenGL2
)
if (NOT VTK_FOUND)
message(FATAL_ERROR "TissueLens: Unable to find the VTK build folder.")
endif()
# Prevent a "command line is too long" failure in Windows.
set(CMAKE_NINJA_FORCE_RESPONSE_FILE "ON" CACHE BOOL "Force Ninja to use response files.")
add_executable(TissueLens MACOSX_BUNDLE TissueLens.cxx )
target_link_libraries(TissueLens PRIVATE ${VTK_LIBRARIES}
)
# vtk_module_autoinit is needed
vtk_module_autoinit(
TARGETS TissueLens
MODULES ${VTK_LIBRARIES}
)
Download and Build TissueLens¶
Click here to download TissueLens and its CMakeLists.txt file. Once the tarball TissueLens.tar has been downloaded and extracted,
cd TissueLens/build
If VTK is installed:
cmake ..
If VTK is not installed but compiled on your system, you will need to specify the path to your VTK build:
cmake -DVTK_DIR:PATH=/home/me/vtk_build ..
Build the project:
make
and run it:
./TissueLens
WINDOWS USERS
Be sure to add the VTK bin directory to your path. This will resolve the VTK dll's at run time.
