Home

The TWINGSISTER's projects are devised as a set of easy steps to enable someone (...mainly the authors..) to write parametric definition of surfaces in a programming language easily working with the two Blender addons called Sverchok and Animation Nodes. This addon is based on the BlendBridge library. Following this approach step by step you will enjoy the creation of some simple colored surfaces.

First step: install Blender

The TWINGSISTER's projects contains a number of Blender addons. So to enjoy something here you first have to download and install Blender.

Second step: install Sverchok and BlendBridge

Basically you need to download the BlendBridge plugin that is distributed as a perk in the internal TWINGSISTER fundraising champaing.
We refer you to the documentation for the Quadrics addon. There you will find all the instruction needed to install any of the TWINGSISTER addon. When you installed BlendBridge you can opt to use either the Sverchok addon or the Animation Nodes addon or both of them. Please refer to the Quadrics documentation. for the supported versions of these addons. There you can find a link to downolad them.

Third step: practise with the Quadrics addon

The simplest addon using Blender+[Sverchok|Animation Nodes]+BlendBridge is the Quadrics addon. Our advice is to try to install it and
produce a quadric surface even if you are not interested in it. In the (already referenced) documentation for the Quadrics addon you will find all the instruction needed to install any of the TWINGSISTER addon.

Fourth step: add color with Python code

The BlendLink addon will enable you to define both the surface and its color/texture in a rather natural way. So, as a first step, we try to add color to a known surface (a quadric) witn some Python code. The ColorQuadrics addon do exactly this. The ColorQuadrics addon is an extension of the Quadrics addon so all the parameters in the Quadrics addon works in the same way in the ColorQuadrics addon. All is the same but a new button named Upload. You will see this button on ColorQuadrics (and BlendLink) nodes. Once you have loaded the ColorQuadrics addon following the same procedure you have used for the Quadrics addon you have to upload the ColorQuadricsExampleUploader.json file that is here in the Examples folder of for the ColorQuadrics addon. The procedure for this is detailed in the documentation for the ColorQuadrics addon documentation documentation. In the documentation for ColorQuadrics you will learn how to write Python code that defines three functions red(x,y,z,u,v), green(x,y,z,u,v) and blue(x,y,z,u,v) to add per vertex color. You will upload this Python module using the Upload button and get a colorful quadric surfce. No further knowledge of Blender script programming is needed!

Fifth step: install BlendLink and test it

If you have reached this you now must be able to install an addon form the TWINGSISTER collection. So please download and install the addon contained in the BlendLink.zip file Here.
For Sverchock users
You can find here a web tutorial for this (works only with Blender 2.80).
If you are using Swerchok you can download the .json file Here. Import this as you have learnt in the previous steps. During this import some error messages will come up. They simply say that a definition for the surface is missing and that no color/texture definition is given. That's true, simply skip this errors clicking on it and then on the screen.
For Animation Nodes users
Animation Nodes users need to build a node tree around the BlendLink node to display its output and, when the node tree is ready, they must click into the Execute Node Tree button in the Animation Nodes panel. An exa The procedure is similar to the one lister here. In Particular we have simply to adapt what is in this figure
After that, you have to download the Python configuration file Here.Then using the Upload button (as done in step four) upload the Python configuration file. The result of the whole process is contained in this .blend file. You can also find some Python code snippets provided in the same page where you download the .json file and the .py file, Here. If you worked properly you will get a surface with a texture on it. Please note that an actual object is generated only by pressing the Draw Button . If it doesn't work, you could have to open the configuration Python file and control if the "return" command correct location for the .jpg texture file. If not edit it and reload it. Note that, when you give the location of a file, you have to separate each directory name from the others by using two slashes \ .
Look at the following image for a four steps introduction to get sx-yy examples working, Note that step 0 (it has two entries in the figure) is for Sverchok users only since it requires you to know how to read in a .json file (see documentation for the Quadrics addon). Both Sverchok and Animation Nodes users need then how to read in a .py file (see documentation for the ColorQuadrics addon). So, you cannot jump directly to this step, skipping steps from one to four, unless you have some intuition and you are lucky (read on after this image, please)

Some examples produce UV textured models. You can take a look to this image to start to see how Blender support UV texturing. Please note that some other examples (that comes with BlendLink) create per vertex coloured models and, therefore, the nodes you will get, when you use these examples, are different. However the situation, for per vertex coloured models, follows what we have seen in ColorQuadrics.

Sixth step: Define a parametric surface in Python.

Basically, from a system like this, one expect to have a simple way to take a mathematical formula for a parametric surface usually x(u,v)=..., y(u,v)=..., z(u,v)=... may be depending on some parameters P1, P2 etc and have a simple way to have it in 3D. Similarly, one expect to have a means of defining some way to stitch an image, usually called a texture, onto this parametric surface. The obvious way of doing this is called u,v texture mapping. Even if this sounds obvious usually, how to get a Moebius strip with some texture is not the usual "Hello world" example in modeling software. Usually, you need to learn a lot before you can do this. The BlendLink addon tries to fill this gap. There should be a way to get a parametric set of equation x(u,v)=..., y(u,v)=..., z(u,v)=... from some math books and have the textured/colored surface for it in a breeze. Next one imagine that it should be possible to have sliders, for some parameters, and see the surface stretching or change its color.

UV Texture Mapping

To make this presentation self-contained let's add some idea on uv texture mapping.i.e. we imagine to lay a grid on the texture image and then map this grid onto the surface. So simply if u,v are the coordinates of the grid that we lay onto the texture we need to say which u,v couple we want to assign to a given point of coordinates (x,y,z) on the surface. The most natural way to do this is to define two mappings that gives u and v for each x,y,z. Therefore one expect to define u,v, mapping giving two functions u(x,y,z)=..., v(x,y,z)=.... In this particular domain, x,y,z are coordinates from a parametric surface. So, sometimes, it is easier to give the composite function obtained mapping first u,v into x,y,z and then x,y,z into u,v. In BlendLink we enable users to take both approaches since we ask for two definitions for umap(x,y,z,u,v...)=..., vmap(x,y,z,u,v...)=.... In all the provided examples we have chosen the most obvious definition umap(x,y,z,u,v...)=u, vmap(x,y,z,u,v...)=v.

The BlendLink API

Putting all things together the BlendLink addon require as input a Python file that might define a parametrized parametric surface. Surface is parametrized by a standard set of parameters named: P1,P2.P3,P4,P5,P6 (up to six allowed). and two boolean parameters named Sw1, Sw2. Surface description must be given by some formula that gives points on the surface when the two parameters u,v ranges from 0 to 1. The number of steps taken for both u and v is controlled by parameter Div.

With these assumptions and namings, to define a surface, user must define three Python functions returning a float value. Function heading must be x(u,v,Sw1,Sw2,P1,P2,P3,P4,P5,P6), y(u,v,Sw1,Sw2,P1,P2,P3,P4,P5,P6), z(u,v,Sw1,Sw2,P1,P2,P3,P4,P5,P6). If these definitions are not given the system provides a default shape (a sphere).

Similarly the u,v mapping will be defined giving two functions with profile umap(x,y,z,u,v,Sw1,Sw2,P1,P2,P3,P4,P5,P6) and vmap(x,y,z,u,v,Sw1,Sw2,P1,P2,P3,P4,P5,P6)
Texture will be passed defining a function with profile imgname() that returns a string giving the full path of an image file for the texture.

Finally per vertex color can be defined giving three functions with profile red(x,y,z,u,v,Sw1,Sw2,P1,P2,P3,P4,P5,P6), green(x,y,z,u,v,Sw1,Sw2,P1,P2,P3,P4,P5,P6) and blue(x,y,z,u,v,Sw1,Sw2,P1,P2,P3,P4,P5,P6).

Working with BlendLink

If both color and texture are defined texture will prevail. If none is given system defaults to a default color (red).
When reading in a json file for a node graph using a BlendLink node, some error messages might come up because the .py file is not uploaded in read yet. Simply ignore them and choose the correct path for the configuration Python file (even if it already looks correct) and press Upload. If no error message appears, i.e. if the Python configuration file is correct, then you can generate the shape you have defined in the Python file. Upon modification in the file Python configuration file, if you see no effect, please try to delete pyc files in directory ./pycache/".pyc. If, once you have uploaded the configuration file, BlendLink doesn't seem to work, even if no error appears please, try to use Add>Mesh>BlendLink>Draw. If there are some errors in the python file or if the program has some problems reading the configuration file, some errors will appear and you could see where you have to modify your configuration file. The amount of information displayed is controlled by the DebugLevel parameter. If DebugLevel is equal to 0 (default) no error message is output.
If DebugLevel is greater of equal to 1 some information is written to a log file. The path of this file is in Blender File>User Preferences>Add-on (tab). Look for it into the parameters for the add-on Blendbridge. If DebugLevel is greater of equal to 2 information is still written to the log file and also to a window. The system opens an error window and gives you some information about what went wrong.

The example gallery

For the math minded people a number of examples are provided. The formulas come from the surface gallery here . Having a good quality model of your surface is quite straightforward. Here are some examples (read on after these images).
Torus with The Matrix texture

Dini Surface

Many others comes in this site. The Python code (you have to read in the BlendLink node to get them) is available here for free. After you get the surface in Blender you can save them in several 3D formats. Not all formats retain texture or colors. If you simply want the see the model and are not interested in modifying it, then consider that some saved surfaces are on sale for fundraising at Turbosquid. Simply Google for Turbosquid Twingsister or put Twingsister into Turbosquid search bar to see them.

The Refinement Process

We devised a re-meshing facility in BlenderLink so that it is possible to specify some conditions about precision of the approximating surface. In this re-meshing process, our algorithm builds, adaptively, an appropriate triangulation where
some approximation creterium is met. One implemented option is to ask that no edge is longer than a specified maximum length. Another option is to ask for a surface is within a certain tolerance from the theoretical surface. We call this re-meshing process the Refinement Process (RP).
Parameters that control the RP are organized into two lists. One listi is made up made up of integers that we will call SWITCHes. The other list is made up of floating numbers. We will call them PARAMs. SWITCH list has four elements PARAM has three.
The effect of the PARAM parameters and of the SWITCH switches are detailed in this document. The RP uses three different algorithm that can be selected with an appropriate choice of SWITCHes. A couple of the (the ENVELOPE and NGON algorithms) works if in Blender if and only it you have installed the package scipy in Blender Python. Please Google for PipBlender to find help on how to install python packages in Blender. PipBlender is another addon working with BlendBridge. If you want to try PipBlender with Sverchok to install scipy follow the web presentation here .
To enable RP you have to check the Refine switch. The refinement process starts every time a BlendLink node, whose Refine switch is checked, is executed. Another couple of parameters can control the refinement process. They are available in another addon nodes developed in the MeshServices project available here. Using MeshServices node called MeshConnector you can control the number of refinement steps to be executed before delivering a refined mesh. In this case the algorithm stops even if the defined stopping criteria are not met. This is particularly handy since the RP tend to be rather CPU consuming. The second parameter available in theMeshConnector node implements a Feedback facility.
Using this we can ask the RP to re-start refining from the last, most refined, delivered mesh.

Execution and stopping condition are controlled by the PARAM and SWITCH parameters. The node performing a RP uses PARAMs and SWITCHes that are linked to the RefineSwitch and RefineParam inputs. If these inputs are not connected, default values are used,
The RP is implemented in Python and has received little engineering so re-meshing time, althought linear in the output size, could be rather long. This folder contains some examples of parametric surfaces obtained by RP. The RP can generate accurate and compact approximation of parametric surfaces. The standard genration of a parametric surface has some issues. Some mathematical formulas gives parametrizations that tend to produce non uniform meshes when points are generated by the application of the x(u,v), y(u,v), z(u,v) functions onto a uniform grid in the u,v space. Our solution introduce more triangle when the surface curvature increases. Figure below shows this behaviour compared with a uniform triangulation
On the other hand sometimes lots of triangles are used to triangulate nearly flat regions of the surface. Figure below shows a particular of a refined surface where triangles in the plane portion of the surface (on the left) are not not refined at all A more detailed discussion of the RP implemented in BlendLink is discussed in this report.

The wiki uses Markdown syntax.

Project Members:

• TWINGSISTER (admin)