/vedo

A python module for scientific visualization of 3D objects based on VTK

Primary LanguagePythonOtherNOASSERTION

vlogo

Codacy Badge Downloads lics Anaconda-Server Badge Ubuntu 20.10 DOI CircleCI

vedo is a fast and lightweight python module for scientific analysis and visualization of 3d objects.

✨ Philosophy

Inspired by the vpython manifesto "3D programming for ordinary mortals", vedo makes it easy to work with three-dimensional meshes and volumes, creating displays and animations in just a few lines of code, even for those with less programming experience.

vedo is based on VTK and numpy, with no other dependencies.

🎯 Table of Contents

💾 Installation

Use pip to install. Type:

pip install vedo

# To get the latest dev version use:
pip install -U git+https://github.com/marcomusy/vedo.git

or from the conda-forge channel:

conda install -c conda-forge vedo

📌 Done? Run any of the built-in examples. In a terminal, type:

vedo -r covid19

Visualize a file from web URL (or your dropbox!), type:

vedo https://vedo.embl.es/examples/data/panther.stl.gz

Visualize a whole scene, type:

vedo https://vedo.embl.es/examples/geo_scene.npy

Windows-10 users can place vedo.bat on the desktop to drag&drop files to visualize (need to edit the path of your local python installation).

📙 Documentation

Automatically generated documentation can be found here.

📌 Need help? Have any question, or wish to suggest or ask for a missing feature? Do not hesitate to open a issue or send an email.

🎨 Features

The vedo module includes a large set of working examples for a wide range of functionalities:

working with polygonal meshes and point clouds (click triangle to expand)
- Import meshes from VTK format, STL, Wavefront OBJ, 3DS, Dolfin-XML, Neutral, GMSH, OFF, PCD (PointCloud),

- Export meshes as ASCII or binary to VTK, STL, OBJ, PLY ... formats.

- Analysis tools like Moving Least Squares, mesh morphing and more..

- Tools to visualize and edit meshes (cutting a mesh with another mesh, slicing, normalizing, moving vertex positions, etc..).

- Split mesh based on surface connectivity. Extract the largest connected area.

- Calculate areas, volumes, center of mass, average sizes etc.

- Calculate vertex and face normals, curvatures, feature edges. Fill mesh holes.

- Subdivide faces of a mesh, increasing the number of vertex points. Mesh simplification.

- Coloring and thresholding of meshes based on associated scalar or vectorial data.

- Point-surface operations: find nearest points, determine if a point lies inside or outside of a mesh.

- Create primitive shapes: spheres, arrows, cubes, torus, ellipsoids...

- Generate glyphs (associate a mesh to every vertex of a source mesh).

- Create animations easily by just setting the position of the displayed objects in the 3D scene. Add trailing lines and shadows to moving objects is supported.

- Straightforward support for multiple sync-ed or independent renderers in  the same window.

- Registration (alignment) of meshes with different techniques.

- Mesh smoothing.

- Delaunay triangulation in 2D and 3D.

- Generate meshes by joining nearby lines in space.

- Find the closest path from one point to another, traveling along the edges of a mesh.

- Find the intersection of a mesh with lines, planes or other meshes.

- Interpolate scalar and vectorial fields with Radial Basis Functions and Thin Plate Splines.

- Add sliders and buttons to interact with the scene and the individual objects.

- Visualization of tensors.

- Analysis of Point Clouds:

 - Moving Least Squares smoothing of 2D, 3D and 4D clouds

 - Fit lines, planes, spheres and ellipses in space

 - Identify outliers in a distribution of points

 - Decimate a cloud to a uniform distribution.
working with volumetric data, and tetrahedral meshes
- Import data from VTK format volumetric TIFF stacks, DICOM, SLC, MHD and more

- Import 2D images as PNG, JPEG, BMP

- Isosurfacing of volumes

- Composite and maximum projection volumetric rendering

- Generate volumetric signed-distance data from an input surface mesh

- Probe a volume with lines and planes

- Generate stream-lines and stream-tubes from vectorial fields

- Slice and crop volumes

- Support for other volumetric structures (structured and grid data)
plotting and histogramming in 2D and 3D
- Fully customizable axis styles

- 'donut' plots and pie charts

- Scatter plots in 2D and 3D

- Surface function plotting

- 1D customizable histograms

- 2D hexagonal histograms

- Polar plots, spherical plots and histogramming

- Draw latex-formatted formulas in the rendering window.

- Quiver plots

- Stream line plots

- Point markers analogous to matplotlib

Moreover:

  • Polygonal 3D text rendering with Latex-like syntax and unicode characters, with 14 different fonts.
  • Integration with the Qt5 framework.
  • Support for FEniCS/Dolfin platform for visualization of finite-element calculations.
  • Interoperability with the trimesh library.
  • Export 3D scenes and embed into a web page.
  • Embed 3D scenes in jupyter notebooks with K3D (can export an interactive 3D-snapshot page here).

⌨ Command Line Interface

Visualize a polygonal mesh from a terminal window simply with:

vedo mymesh.obj
# valid formats: [vtk,vtu,vts,vtp,vtm,ply,obj,stl,3ds,dolfin-xml,neutral,gmsh,
#                 pcd,xyz,txt,byu,tif,off,slc,vti,mhd,dcm,dem,nrrd,nii,bmp,png,jpg]

Volumetric files (mhd, vti, slc, tiff, DICOM etc..) can be visualized in different modes:

Slice a volume in the 3 planes:
vedo --slicer embryo.slc
Ray-casting rendering:
-g embryo.slc
2D slice:
--slicer2d
Colorize voxels:
--lego
slicer isohead viz_slicer lego

To visualize multiple files or files time-sequences try -n or -s options. Use -h for the complete list of options.
A GUI is also available (mainly useful to Windows 10 users) which can be invoked with command vedo.

🐾 Examples

300+ working examples can be found in directories:
examples/basic
examples/advanced
examples/volumetric
examples/tetmesh
examples/simulations
examples/pyplot
examples/other
examples/other/dolfin
examples/other/trimesh
notebooks

Apply a Moving Least Squares algorithm to obtain a smooth surface from a to a large cloud of scattered points in space (script)
rabbit
airplanes
Create a simple 3D animation in exactly 10 lines of code (script). Trails and shadows can be added to moving objects easily
Simulation of a gyroscope hanging from a spring (script)
gyro
qsine2
Quantum-tunnelling effect integrating the Schroedinger equation with 4th order Runge-Kutta method. The animation shows the evolution of a particle in a box hitting a sinusoidal potential barrier. (script)
Turing system of reaction-diffusion between two molecules (script)
greyscott
trimesh
Interoperability with the trimesh library (see here)
Support for the FEniCS/Dolfin platform for visualization of PDE and finite element solutions (see here)
elastodyn
dolf

Random Gallery of Examples

Run any of the following built-in examples from command line. Type:

vedo -r covid19

covid
vedo -r covid19
caption
caption
fonts3d
font
fonts
fonts
customaxes
customaxes
intersect
intersect2d
goniom
goniometer

tet_threshold
density
density3d
mquality
meshquality
levelterrain
isolines

tet_cutmesh1
geologic
geological
multirender
multirender
cartoony
cartoony
streamline4
streamlines4
graph1
graph_network
lineage_graph
graph_lineage
siluette
silhouette1

silhouette2
gyro
gyroscope2
thinplate_grid
thinplate_grid
trail
trail
quadratic_morphing
quadratic_morphing
shrink
shrink
mesh_custom
mesh_custom
spring
spring
lorenz
lorentz
sliders
sliders
fitspheres1
fitspheres1
fxy
plot4_fxy
histogram
histo_1D
plot_err_band
plot2_errband
histogram2D
histo_2D
histoHexagonal.py
histo_hexagonal
sphericPlot
plot5_spheric
boolean
boolean
brownian2D
brownian2D
gas
gas
self_org_maps2d
self_org_maps2d
geodesic
geodesic
convexHull
convexHull
flatarrow
flatarrow
latex
latex
legosurface
legosurface
streamlines2
streamlines2
office
office.py
value-iteration
value-iteration
shadow
shadow
multiple_pendulum
multiple_pend
interpolateVolume
interpolateVolume
histo_polar
histo_polar
streamplot
plot7_stream
violin
histo_violin
plot3_pip
plot3_pip
histo_spheric
histo_spheric
readvts
read_vts
donutPlot
donut
extrude
extrude
plotxy
plot1_errbars
isohead viz_raycast viz_slicer lego
particle_simulator
particle_simulator
heatconv
heatconv
stokes
stokes
navier-stokes_lshape
stokes_lshape

📜 References

  • M. Musy, G. Dalmasso, J. Sharpe and N. Sime, "vedo: plotting in FEniCS with python", (link). Poster at the FEniCS'2019 Conference, Carnegie Institution for Science Department of Terrestrial Magnetism, Washington DC, June 2019.

  • G. Dalmasso, "Evolution in space and time of 3D volumetric images". Talk at the Conference for Image-based Modeling and Simulation of Morphogenesis. Max Planck Institute for the Physics of Complex Systems, Dresden, Germany, March 2019.

Scientific publications using vedo:

  1. X. Diego et al.: "Key features of Turing systems are determined purely by network topology", Physical Review X, 20 June 2018.
  2. M. Musy, K. Flaherty et al.: "A Quantitative Method for Staging Mouse Limb Embryos based on Limb Morphometry", Development, 5 April 2018, doi: 10.1242/dev.154856.
  3. G. Dalmasso et al., "Evolution in space and time of 3D volumetric images", in preparation.
  4. F. Claudi, A. L. Tyson, T. Branco, "Brainrender. A python based software for visualisation of neuroanatomical and morphological data." bioRxiv 2020.02.23.961748; doi: https://doi.org/10.1101/2020.02.23.961748

Have you found this software useful for your research? Please cite it as:
M. Musy et al. "vedo, a python module for scientific visualization and analysis of 3D objects and point clouds based on VTK (Visualization Toolkit)", Zenodo, 10 February 2019, doi: 10.5281/zenodo.2561402.

embl_logo