Package: simple-3dviz
simple-3dvizsimple-3dvizprovides a set of simple and reusable tools for visualizing 3D
data using Python and OpenGL. The goal of this library is to provide an easy
way to visualize 3D objects with hundreds of thousands of vertices efficiently
just with few lines of code. It can be used for visualizing various renderables
such as meshes, point clouds, voxel grids, a set of geometric primitives etc.Key features include:Manipulation of meshes fromWavefront OBJ,ASCII OFF,binary/ASCII STLandbinary/ASCII PLY.A lightweight and easy-to-use scene viewer usingwxpythonwith support for animation and storing images.An offscreen rendering module.Helper functions to render pointclouds, lines, voxels and superquadrics.Dependencies & InstallationYou can installsimple-3dvizdirectly frompip.pipinstallsimple-3dvizIf you want to extend our code clone the repository and install it in
development mode. In addition to the main library, we provide also two useful
console applications that can be used for visualizing meshes
(mesh_viewer)
and 2D functions
(func_viewer).The dependencies ofsimple-3dvizare listed below:numpymodernglplyfilepyrrPILorOpenCV(if you want to store the rendering to image files)wxpython(if you want to have a GUI)Quick StartYou can find various examples of how to use our library in the providedscriptsandexamples.
Below we showcase some basic functionalities implemented insimple-3dviz.fromsimple_3dvizimportMeshfromsimple_3dviz.windowimportshowfromsimple_3dviz.utilsimportrender# We can load meshes from a file by specifying its path or by explicitely# giving the vertices and the normals of the mesh you want to renderm=Mesh.from_file("models/baby_yoda.stl")# You can easily extract the mesh vertices and facesvertices,faces=m.to_points_and_faces()# Preview the mesh in an OpenGL window if you installed wxpython with pip# Note that you can specify the size (size) and the background color# (background) of the rendered window as well as the position of the camera in# the scene (camera_position), its viewing direction (camera_target) and the 3d# direction that indicates which direction is "up" (up_vector). Finally you can# also specify the location of the light source as well a set of behaviours to# be performed.show(m,camera_position=(-60.,-160,120),camera_target=(0.,0,40),light=(-60,-160,120))# Our rendered mesh looks nice already but it is still not very accurate. This# can be fixed by properly adjuasting the color of the input mesh through the# color argumentm=Mesh.from_file("models/baby_yoda.stl",color=(0.1,0.5,0.1))# We can specify various interesting behaviours while rendering our mesh# Lets start by moving the camera around the object in a circular trajectoryfromsimple_3dviz.behaviours.movementsimportCameraTrajectoryfromsimple_3dviz.behaviours.trajectoryimportCircle# The clockwise circular trajectory in 3D is defined by a 3D point that# indicates the center of the circlular trajectory (center), a 3D point (point)# and a 3D point that indicates the normal vector (normal). The 3D point point# indicates the starting point of the trajectoryc=Circle(center=(0,0,120.),point=(-60,-160,120.),normal=(0,0,1.))ctrj=CameraTrajectory(c,speed=0.005)show(m,camera_position=(-60.,-160,120),camera_target=(0.,0,40),light=(-60,-160,120),behaviours=[ctrj])# Nice, but unfortunately the light remains at a fixed position, which means# that when the camera looks at the back of the object it is not illuminated.# To fix this we can add another behaviour called LightToCamera.fromsimple_3dviz.behaviours.miscimportLightToCamerashow(m,camera_position=(-60.,-160,120),camera_target=(0.,0,40),light=(-60,-160,120),behaviours=[ctrj,LightToCamera()])# Note that we can also render the scene, without the need for any GUI# environment using the render(...) function instead of the show(...) function.# The render function takes the same arguments as the show function with an# additional argument that indicates the number of frames to be rendered# (n_frames).# Saving the rendering results to the hard disk is implemented# with a behaviour. This allows us to choose how to save the rendered frames# and reuse the saving code for the show(...) pipeline.fromsimple_3dviz.behaviours.ioimportSaveFrames# To store the rendered frames to files, we can use the SaveFrames behaviour.# We simply need to specify the path to save the rendered frames (path).render(m,behaviours=[ctrj,LightToCamera(),SaveFrames("/tmp/frame_{:03d}.png",every_n=5)],n_frames=512,camera_position=(-60.,-160,120),camera_target=(0.,0,40),light=(-60,-160,120))# It is also possible to implement some more exciting motions, e.g. having the# camera move back and forth across a linefromsimple_3dviz.behaviours.trajectoryimportBackAndForth,Linesrender(m,behaviours=[CameraTrajectory(BackAndForth(Lines([-60,-160,120],[-60,-80,120])),speed=0.005)LightToCamera(),SaveFrames("/tmp/frame_{:03d}.png",every_n=5)],n_frames=512,camera_position=(-60.,-160,120),camera_target=(0.,0,40),light=(-60,-160,120))# Let's now try something more exciting! We start, by loading our baby Yoda# mesh multiple times with different colorsm1=Mesh.from_file("models/baby_yoda.stl",color=(0.1,0.5,0.1))m2=Mesh.from_file("models/baby_yoda.stl",color=(0,1.0,1.0))m3=Mesh.from_file("models/baby_yoda.stl",color=(0.5,0.1,0.1))# We space the meshes across a line in the 3D space, by properly adjusting# their offset parameterm2.offset=(-100,0,0)m3.offset=(100,0,0)# We can have the camera moving between the three meshes, following a bezier# curve, defined using the following control pointsfromsimple_3dviz.behaviours.trajectoryimportQuadraticBezierCurves,Repeattraj=Repeat(QuadraticBezierCurves((-1.5*120,0,70),(-1*120,80,70),(-0.5*120,0,70),(0,-80,70),(0.5*120,0,70),(1*120,80,70),(1.5*120,0,70),(1*120,-80,70),(0.5*120,0,70),(0,80,70),(-0.5*120,0,70),(-1*120,-80,70),(-1.5*120,0,70)))# We now render the three meshes as followsrender([m1,m2,m3],behaviours=[CameraTrajectory(traj,speed=0.001),SaveFrames("/tmp/frame_{:03d}.png",every_n=10)],n_frames=999,camera_target=(0.,0.,70.0),light=(-60,-160,120))# Using simple-3dviz, we can also visualize point clouds and voxels, lines and# primitives.# Let us reproduce the voxel grid example from matplotlib that can be# found here (https://matplotlib.org/3.2.1/gallery/mplot3d/voxels.html)importnumpyasnpx,y,z=np.indices((8,8,8))cube1=(x<3)&(y<3)&(z<3)cube2=(x>=5)&(y>=5)&(z>=5)link=abs(x-y)+abs(y-z)+abs(z-x)<=2voxels=cube1|cube2|link# Build a voxel grid from the voxelsm=Mesh.from_voxel_grid(voxels=voxels,sizes=(0.49,0.49,0.49),colors=[colormap[c]forcincolors[voxels]])# Set the colors for evey object and visualize the screencolors=np.empty(voxels.shape+(3,),dtype=np.float32)colors[link]=(1,0,0)colors[cube1]=(0,0,1)colors[cube2]=(0,1,0)show(Mesh.from_voxel_grid(voxels=voxels,colors=colors),light=(-1,-1,1),behaviours=[CameraTrajectory(Circle(center=(0,0,0),point=(2,-1,0),normal=(0,0,-1)),speed=0.004)])# To visualize a pointloud we can simply use the Spherecloud object# from simple_3dviz import Spherecloud# We start by generating points uniformly distributed in the unit cubex=np.linspace(-0.7,0.7,num=10)centers=np.array(np.meshgrid(x,x,x)).reshape(3,-1).Tspheres_colors=np.array([[1,1,0,1],[0,1,1,1]])[np.random.randint(0,2,size=centers.shape[0])]spheres_sizes=np.ones(centers.shape[0])*0.02# simple-3dviz also supports visualizing meshes with texture. You can simply# load a mesh with texture using our TexturedMesh classm=TexturedMesh.from_file("models/cat_1/12222_Cat_v1_l3.obj")Keyboard and Mouse Controls for the Scene ViewerWhen using the scene viewer via theshow()function, it is possible to
perform various actions either using the mouse of the keyboard.Rotate: Press the left button clickPan: Press the middle button clickZoom in/out: Scroll the mouse wheelThe available keyboard commands are:R: Reports the camera position, its viewing direction and the 3d
direction that indicates which direction is "up" at the current timestamp.T: Make sure that the triangles will be sorted so that the transparency
works as well.DocumentationThe module has a dedicateddocumentation sitebut
you can also read thesource
codeand theexamples.
to get an idea of how the library should be used and extended.LicenseOur code is released under theMIT
license, which practically allows
anyone to do anything with it.CitationIf you found simple-3dviz useful in your research please consider citing:@misc{Katharopoulos2020simple3dviz,
     title = {simple-3dviz},
     author = {Katharopoulos Angelos and Paschalidou, Despoina},
     howpublished = {\url{https://simple-3dviz.com}},
     year = {2020}
}