# Discover Pycao

## What is Pycao in a few words ?

Pycao is a 3D-modeller for Python. In short, this is a tool to describe a 3D-scene using the Python language. Then you can see your 3D objects using the Povray raytracer as a plugin.

The pycao project stemmed from my experiments with Blender, Povray and some cad software. It is an attempt to construct what I missed : a language with a rich vocabulary, focused on the simplification of the developper’s work, documented, free from any graphical interface, with a moderate level of complexity.

Pycao may be suitable for people with a project of medium size, like building a wood furniture, a bike or drawing a scientific illustration, discouraged by the complexity and/or inapropriate documentation of some 3D software.

The focus of Pycao is towards simplification rather than versatility, in contrast to most cad software. For instance for curves, only Bezier Curves are possible. Suttle tools like nurbs curves do not exist in Pycao. But on the other hand, Bezier curves come with high level tools which allow convenient manipulation with few lines of code of piecewise interpolation curves ( the most useful curves in practice ). More generally, many simplifying paradigms are available: carrying objects in boxes, genealogy system, markers similar to the pen marks in a workshop, measurements possible from the left and from the right using various units, easy to build libraries, synthetic mathematical tools ... . Hopefully, you may describe your object with the minimum number of lines of codes using these paradigms. To get an idea of the work required to produce a drawing, the above bike requires around 250 lines of code.

The concepts used to describe an object are geometric, similar to a workshop description, and coordinate free as much as possible.

## What is Pycao ? (longer answer with examples)

Pycao is a software to describe and view a 3D picture. Its main part is a language which allows easy and fast description of a 3D scene.

As a language, pycao gives you the words to describe a scene, an object. A cylinder of radius 0.2 and heigth 0.3, with axis of revolution towards the axis Z=(0,0,1) and with center the origin is for instance described as follows:

myCylinder=Cylinder(radius=.2,length=.3).move_at(origin).colored("Red")
camera=Camera()
camera.filmAllActors=True
camera.file="premierCylindre.pov"
camera.shoot
camera.show


The language comes with many concepts to facilitate the description (parents,children,markers,geometric constructions... ) so that the code required to describe the scene requires few lines and the minimum of math computations. For instance, the simple scene with a table or a wheel as below require in the library around 20 lines of code for the geometrical description, plus a few lines of code for the colors.

from bikelibrary import *
camera=Camera()
camera.filmAllActors=False
camera.file="wheel.pov"
camera.location=point(8,-15,1.95)
camera.zoom(3.6)
camera.shoot
camera.show


### Where is the graphical interface ?

Once you have modelled an object or a scene, the scene will be displayed in a window where you can move the camera, the zoom... in an interactive way with buttons. It is also possible to visualize standard povray files modelled out of povray with the viewer. The viewer and the buttons look like this

If it is possible to view the model in an interactive way, the model has to be defined prealably writing Python code in a text editor. Pycao is designed towards people who think that it is easier to describe a 3d object with a good language than with a graphical interface. Thus there is no graphical interface for the modelling, beyond the interface of your text editor.

Most people think a priori that a graphical interface is simpler. Here are some points from my experiments.

Describing a 3D object with a mouse on a 2D screen is very challenging. Graphical interfaces are not intuitive and difficult to master in 3d-modelling. Selecting a simple point usually requires several operations, and the operation may be complicated if the target point is hidden by an other object.

Writing a program allows payback. It is easy to automatically build an object depending on some parameters, for instance for illustrations in a scientific project where data is computed in an other software. In a hobby project, one can test various designs with the adjustment of a few parameters. For instance, here is a new wheel, with only a few parameters changed, which takes just a few minutes of work, to make a wheel for an electric bike.

from bikelibrary import *
camera=Camera()
camera.filmAllActors=False
camera.actors=[myWheel]
camera.file="wheel2.pov"
camera.location=point(2,5,2)
camera.zoom(1.6)
camera.shoot
camera.show


### What are the objectives/philosophy of the langage ?

The main objective is to make the description as short as possible. We are happy each time we replace five lines of code by a single line of code in the description of an object. I faced difficulties with the language of some cad/3D software with lengthy descriptions difficult to maintain. I have tried to build a more expressive language to minimize the time necessary to describe an object.

Readability is a secondary objective. The code must be short, but simple and not cryptic. Finally, we try to avoid redundancy. The operations should be possible in a unique way to minimize the learning curve.

To illustrate these ideas, consider the example, of a 3D scene with a yellow wall and a green frame on it. In the real world, when we put a frame on a wall, we don’t do coordinates computations : we construct the frame for the picture, we put a nail in the wall after some measurements, we orientate our picture so that it is parallel to the walls, and we translate the picture so that the nail goes in the hole behind our picture. The code written in pycao follow the same ideas. Detailed explanations for the instructions will come later in the documentation, but here is the code to have a taste of its appearance.

wallSize=[4,0.2,2.5];
pictureSize=[0.6,0.02,0.4];
borderSize=[a for a in pictureSize];borderSize[2]=0.06

#constructions
wall=Cube(*wallSize);
wall.move_at(origin-2*Y)
wall.color="Yellow"
topBorder=Cube(*borderSize); topBorder.color="Brown"
bottomBorder=Cube(*borderSize); bottomBorder.color="Black"
picture=Cube(*pictureSize)
picture.color="Green"
topBorder.glued_on(picture) # glue the border on the picture
bottomBorder.glued_on(picture)

# Finally, we move the picture against the wall, with the
# appropriate orientation
picture.against(wall,-Y,-Y,X,X,offset=0.01*Y+0.5*Z)

camera=Camera()
camera.file="wallAndCo.pov"
camera.filmAllActors=False
camera.actors=[wall,picture,topBorder]
camera.location=point(0,3,1.5)
camera.lookAt=wall.center
camera.zoom(0.4)
camera.shoot
camera.show


### What are the concepts used to shorten the code ?

We use python as a base, which is known to allow very clear and compact code. The strategy is to keep the Pycao langage as close as possible to the natural langage and to the mathematical geometric language, without coordinates, since debugging the errors in coordinates is very time consuming.

We use CSG geometry. In other words, there is a list of primary objects ( cylinder, cube,cone over a curve ...) and complex objects are made with these primary objects using intersection,union,difference...

The primary objects come with a list of markers : center, axis, planes, frames... attached to them. These markers do not show by default in the 3D picture, but they are useful to adjust the position of the objects. They are the analogs of the temporary marks that we draw with a pencil on the wood when we construct a furniture.

Objects are carried in boxes. Pycao contains the vocabulary to move a box against a box with no computation of the coordinates and more generally to place a box at a prescribed position. To orientate an object, it suffices to prescribe the position of the box which carries the object.

We use a system of parent/children corresponding to children glued on their parents. For instance, it is possible to construct the wheel of a bike with several pieces (tyre, axis, rays...). Then if the axis is the parent, all the other pieces which are glued on it move with it. The axis itself may be glued on an other object in a recursive construction.

Finally, the concepts of affine geometry, in particular, barycenters and distinctions between points and vectors are natively understood by pycao. When computations or coordinates are unavoidable, the formalism of affine geometry allows a clear and compact formulation.

### I am new to 3D. What are the alternatives to pycao ? What are the differences ?

In the free software world, freecad, blender, povray, salome are important projects.

The povray language is a language with a very complete and clear documentation. This makes it easy to master this language. On the other hand, povray language is a very “low level” language, where the description of an object is quite involved: you need to compute plenty of coordinates, no parenting, no classes or inheritance, many curly braces around. Povray is a fantastic piece of code, very precise, but the code required to describe a 3D-object is long,difficult to write, to read and to maintain. This is logical and povray is not to blame: povray is a rayTracer, not a modeler, The language is built to feed the rayTracer, not to simplify the work of the developper.

Blender, Freecad, Salome include both graphical modeler and scripting possibilities. I will comment only on the scripting possibilities.

Blender comes with a python api. If you work mostly with the graphical interface, with rare use of the api, it may be a good choice. If you use intensivly the api, you should avoid blender. The api is very complex because of its integration with the graphical tool: be ready to spend countless hours to understand the “context errors” in your code, be ready to see some variables updated by the api without your asking for. Since there is a very active community in Blender, you will find help for these problems and for the debugging work.

Freecad and Salome api seem powerful. I have not used them very much because they appeared to be too complex for my needs. The philosophy is very different from pycao. Both try to give the user power and versatility rather than simplicity. The code is marked by the integrated environnement. In contrast pycao aims ease of use for small/medium projects, free from any environnment, to speed up the developpement time. Here is an example of code from freecad.

### I am an expert. What is the architecture ? How do povray and pycao interact ?

What is behind the scene is the following: pycao is a Python module which constructs some objects using your code. Then the instruction camera.shoot calls a module povrayshoot.py which takes the objects build by pycao as input and produces povray code as output. Then povray executes the code and creates the file pycaoShot.png when camera.show is called.

In other words, in the dialog between the developper and the raytracer, pycao talks with the developper, the povray language talks with the raytracer, and povrayshoot makes the translation between pycao and povray. The architecture is then:

developper <—> pycao <—> povrayshoot <—> povray language <—> raytracer=povray kernel

### What are the defaults of pycao ?

The texture and ligths are poorly implemented. Basically, there you have to enter a povray string for them. You can describe what you want, but the ergonomy of python is not used and there are many curly braces to control. I have developped this tool to make 3D pictures of objects I want to build. This means that I am not really interested in the photo-realistic appearance and it won’t evolve much until someone is intersted and ameliorates this point.

This is a young software. There are bugs, hopefully not too much however. I am a Linux user, so I don’t make test with Windows.

The vocabulary of the language may still evolve in the future, if we can express things in a more natural way. So do not use this software for a long term project now. Use it for small projects by now.

Finally, there is no community around this project. Some autonomy to use it is required.

## Is it free software ?

Yes. The license is GPL v3.0.

## Acknowledgments

The pycao project stemmed from my experiments with Blender and Povray.I warmly thank the developpers of Blender and Povray because I have learned so much from their software.