BasicsOfTheSystem

From K-3D

Jump to: navigation, search

Basics of objects, classes and properties

A k3d document consists of a bunch of objects, each with their own set of properties. A property is a name and a value from a given value-domain. Examples of domains are: Number, string, color, reference-to-another-object etc.

Each object has its nature determined by the class it belongs to. The set of available classes can be found in the 'Available plugins' tab in the document window. You can have all the objects of a given class that you want present in the document simultaneously.

As an example you can have a PolyCube object (a box, not a cube) having these properties: width=2m, height=3m and depth=1m. Another PolyCube object can have width, height and depth of 30m,2cm,5mm. But you cannot have a PolyCube object without a 'height' property, because that property is specified by the PolyCube class. Objects share property existence, not property values. You never see a class, only an instantiated object of the class, just like in the programming world.

Usually there is a 'name' property of an object, nomatter what class it belongs to. The name is what appears in the 'Objects' tab of the document window, not its class. You can change the name of all objects but the TimeSource object initially created.

Basics of workflow and pipelines

[a lot of text here describing how one connects objects. Probably written somewhere else]


[Question: Are mesh filters just objects that has an input_mesh and output_mesh properties, or do they have to implement some internal C++ interface that a mesh filter must have?]

[Question: What objects appear in the viewport? Those with an output_mesh property or is it internally determined?]

This notion of pipelines reappear in the simple matter of putting a box in the scene. Try to create a PolyCube object. You will see that two objects are actually created, the PolyCube object and another one that goes by the name of PolyCube Instance the latter being of the MeshInstance class. A MeshInstance is so common that K3D might as well create is along with the mesh you wanted. Try to delete the PolyCube Instance object but not the PolyCube. The box disappears from the scene.

The story behind is that the K3D-authors figured that objects creating raw meshes should not have such properties as position, rotation and scale. Thus they alleviated future creators of plugin writers the trouble of implementing those properties. It also means that a barebone mesh-producing object is not visible on the scene, it's a ghost. A MeshInstance fleshes it out for the camera.

Coordinatesystems and placing scene objects

k3d uses a lefthanded coordinate system with +X going to the right, +Y going up in the sky and +Z vanishing into the horizon along the ground plane.

In order to place objects one needs to modify the 'position', 'rotation' and 'scale' properties of that particular object. Once again the MeshInstance comes into play, as most mesh-objects are meant to be connected to a MeshInstance to have physical reality, including position, rotation and scale.

Besides the position, rotation and scale properties there are a pair of other very interesting properties also that pertains to placement in space. These are the 'input_matrix' and the 'output_matrix'. As you may know from matrix algebra, the foundation of 3D graphics, a series of operations on coordinate systems (which is what rotate and translate are) can be expressed as a sequence of matrix multiplications. In this manner, one can express the process of rotating, translating and scaling as a formula:

   Moutput_matrix = Mscale * Mrotate * Mtranslate

[Question: How are the basis vectors laid out in a matrix? Mv=v' or vM=v'?]

[Question: Shouldn't this read "Moutput_matrix = Mscale * Mrotate * Mtranslate * Minput_matrix?]


A very common thing with 3D software is to allow the final transform of one object act as the origin of an other object. In english terms we would say something like: "To find the transformation of the car's steering wheel as seen from a pedestrian, first find the transformation of the car and then multiply with the transformation of the steering wheel in relation to the car". Or in math:

   let Mi =    if Minput_matrix is connected
               then Minput_matrix
               otherwise Midentity

Moutput_matrix = Mi * Mscale * Mrotate * Mtranslate

[Question: "as seen from a pedestrian" from where? Front of a car, side of a car?, back of a car?] [Question: "is connected" to what?]

[Margin: parent, child] Notice how the output matrix of that object is ready to be connected to the input matrix of another. It is such a system of cascaded input-output transformations that one can utilize in skeletal hierachies etc. When K3D talks of parent and child relationships, it should be translated as: If A.output_matrix => B.input_matrix then A is a parent of B (and B is a child of A).


[Question: Why can't I connect the input_matrix of a Viewport with the output_matrix of a MeshInstance so I can see what the object is facing? Can too. Must update screen]

The look-at plugin

This plugin forms a good example of how to use the connection system. The need it tries to fulfill arises in the situation where something needs to be tracked. For instance a projector in a theater needs to point in the direction of the actor on the stage nomatter how she moves and how the projector itself moves.

Besides the LookAt object an extra object will be necessary to serve as a "handle" for the projector. We then have these objects in play in our example: Projector, ProjectorHandle, Actor, ProjectorLookAt. Notice below the flow of information. As you can see, the Projector itself is never moved, only the handle which forms the basis for calculating the matrix of the Projector.

   ProjectorLookat.input_matrix    <=  ProjectorHandle.output_matrix
   ProjectorLookat.target_matrix   <=  Actor.output_matrix
   ProjectorLookat.output_matrix   =>  Projector.input_matrix


The Viewport

The viewport is the sculptors window into the workspace. It is through this that the scene can be visually edited (NOTE: In version > 0.4)

The initial Camera Viewport is set up so it tracks the Camera itself thus enabling us to gaze into to scene. (The Camera is really a slow render engine, it can't be used for realtime editing purposes).

Personal tools