Render Module Updates:

A lot has happened since my most recent post. It's time to share more work on the Render Module. So I am grabbing some tea and getting ready to share it with you all:

Improvements to Render Interface

Toolbar:

You don't have to edit a Render Feature to preview it. Simply ensure that the settings are set up to how you desire. Then click the preview buttons within the toolbar.

Buttons (From Left):

1) Add Render Feature

2) Render Preview Window

3) Render Preview (uses stored settings in Render Feature)

4) Add materials when editing a Render Feature

Render Task View:

Further updates to improve the completeness of the Render Task View. Render Presets and Templates are correctly set from the combo boxes. 

Material Selection:

All render materials that have been assigned within the Render Feature are now displayed in a list view. These can be selected and deleted, or if double clicked , the material properties can be edited. 

View shows material Labels:

When editing a Render Feature, all materials that are assigned to any objects has some Material Labels displayed. This is very basic admittedly, but for now will suffice to help keep track of what materials are assigned within your scene.

Render Templates:

The inclusion of the Render Templates was the last remaining major feature that was to be implemented. This has further been improved so that they are positioned in a more optimal place respective to the scene geometry and the camera. This is not perfect but is certainly ideal in most cases.

We can more easily now zoom really far out like this.

Or zoom in really close:

The Render Template will take into consideration the bounding box of the visible parts in the scene and the camera itself. It will move the template to the middle of the scene bounding box and then scale it according to  furthest point away from the bounding box center.

Material Selection & Editing:

I have finished of the material selection interface, so you can set and edit parameters. Now this has undo-redo system built in making things easier. On a similar note materials and cameras can be saved. (Material properties aren't saved yet).

The colour chooser and number inputs now correctly retrieve and store values. It needs refinement but most importantly is function. Ideally it needs a button to allow more sophisticated selection from a QtColorChooser Dialog. Other ideas are having predefined material presets, which become more important on more complex materials such as plastics and glasses.

The above screenshots show that material properties are dynamic. Just define the properties in the XML file and the GUI figures out how to use them and store them. Here's the XML sample for the right:

Well that's most of the major changes! I need help with testing and making materials and templates for people to use.

TODO List:

1. Ability to Save Material Properties
2. Make adjustments to the user inteface
3. Add more render materials and scenes
4. Python bindings
5.  ???

Any comments please see https://sourceforge.net/apps/phpbb/free-cad/viewtopic.php?f=8&t=2850

Creating FreeCAD Lux Render Template

This is for the upcoming Render Module. Despite my very limited experience with rendering and modelling it appears that to get that 'wow' factor it will take a lot of scenes. Most people have better things to do so that is where templates come into play.

This guide will hopefully show how it will be possible to specify your own templates (for lux render):

Beginning with Blender & Lux Render:

The easiest way to create a template is to start with blender. A useful build and instruction guide for compiling Lux Render and using this in  Blender has been provided by Yorik on his blog

I don't have any clue how to use Blender, so you will have to figure that for yourselves. Nevertheless the important that you must have the scene normalised to a unit length. Ideally you have a cube with side lengths as one and build up a scene around this.

This is important because the scene will be scaled to the bounding box of the scene. I cannot guarantee this will work in all situations but it should give satisfactory results. Within blender you will need to export the scene to a  Lux Render Scene File Format with an extension .lxs 

Yorik created three example scenes that I am going to show you how to import as a Render Template in FreeCAD, these I have made available using google docs

Importing templates into FreeCAD:

For the scene template, we only need to find lights, geometry and materials information.

Materials are most likely to be used on the geometry within the scene. Using a templates like this means we can texture surfaces, which isn't going to appear within FreeCAD in the near future.

In this example open up luxscene-classic.lxs

Essentially we need everything from World Begin to World End. So extract all of this and you should be left with http://pastebin.com/qe3m0qXu 

One thing we need to change:

I discovered the long way that there is a problem with the way Blender exports the scene information to Lux Render. Unfortunately, you will need to go through the file and look for lines like these:

Transform [-0.083770856261253 0.000000133886644 -0.996485054492950 0.000000000000000 -0.000000133886729 1.000000000000000 0.000000145614280 0.000000000000000 0.996485054492950 0.000000145614365 -0.083770856261253 0.000000000000000 -0.465571254491806 -0.011301971040666 0.364225387573242 1.000000000000000]

These are transformation Matrices. These need to be removed and replaced with seperate Translation and Rotation properties for each object like so:

Tanslate x y z

Rotate angle x y z

With the rotation, you specify an angle about a given axis, so in the case of blender this may have to be done three times, in the x,y,z directions.

For example in the classic scene:

Select the Plane.006 object and look the object properties

So you would replace the Transform line with this: 

Tanslate 0.459 -0.01 0.6

Rotate 253.4 0 1 0

Place this into a file such as luxsceneClassic.lxs

Then inside the FreeCAD build folder navigate to data/Mod/Raytracing/Templates

Create a folder in Templates/Lux to hold your template such as Templates/Lux/Classic. Then copy the file luxSceneClassic.lxs you previously created inside here.

Within the same folder create an xml file and copy into this file the following excerpt:

<?xml version="1.0" encoding="iso-8859-1" ?>

<!--

 FreeCAD Scene Template for LUX Render, see http://free-cad.sourceforge.net for more information...

-->

<Document SchemaVersion="1">

  <Templates render="lux">

    <Template id="lux_classic" source="external">

      <label>Lux Classic Scene</label>

      <description> Classical Elegance</description>

      <provides>classic</provides>

      <filename>luxSceneClassic.lxs</filename>

    </Template>

  </Templates>

</Document>

For reference you only have to change the following:

• id="lux_classic" : this attribute must be a unique identifier for the template
• <label> Label for the scene template </label> : a graphical name for the scene
• <description>Description for the scene template</description> : a descriptive identifier
• <filename>luxSceneClassic.lxs</filename> the file name that contains the scene information

You should have a file structure like this:

I am not sure when you compile and build FreeCAD each time if this template folder will be deleted. Most likely not. Later, I will make a preference option so you can use your own folder. 

Using the Template:

Launch FreeCAD and switch to the Raytracing Workbench:

Create a new Render Feature.

A task view will appear. FreeCAD will automatically find your template. You can now select the template that is used in your scene. If nothing appears when you render, it is likely that the Lux Render Scene File Format has incorrect syntax...

Now position the camera where you want and hit Preview Window. Currently there might be times where the render is just a black screen - so to quickly solve this just play around with the camera a bit. 

Hopefully this make sense, feel free to post questions on here if you're stuck!

We have working render templates!

After a few days of working with a day off finally getting out of the small village I live in, we have a render template system that is working.

Here is the Schenkel part - does anybody know what this is? Attached with a Matte material with an orange colour:

Before:

After the render:

Now lets turn it into glass!

Here I am using the classic theme created by Yorilk. It's a basic box scene with two area lights. It's not bad to say it takes about 30 seconds to set up. 

What is QML?

I'm sparing some time to explain QML: Qt Meta Language - officially apart of  Qt Quick and draw in some of my early experiences learning and using it over the past week.

Quick Introduction:

Qt Quick is a set of technologies provided by QT for developing powerful, interactive user interfaces and building programs by using a declarative programming language. The video above is a an example of some programs created using Qt Quick 2 in the upcoming release of QT 5.

Qt Quick allows dynamic interfaces to be created using animations with tweening and all the other fancy bells and whistles, whilst retaining high performance especially by being multi-threaded. Because it's interpreted at runtime, you can modify the QML file and reload it without having to re-compile the application. I even think it's possible to download and load QML from an internet source.

An example of a game produced entirely in QML. A video showcases QML significantly better!

Without being a user interface expert, I would suggest a powerful user interface is one improves the user's workflow and experience when using a program. It's there to also present information in a meaningful way and manipulate it in the most straightforward manner - the method that's is usually the most time saving. This is all in context of the user.

It's my belief that the idea for Qt Quick was conjectured before Trolltech was acquired by Nokia and was intended to compliment and build upon the introducing of Qt Script bindings and the QGraphicsScene introduced in early versions of QT 4.

Qt Quick will not solve everything! There will be appropriate times where interfaces will need to use standard desktop widgets.

A bit about the language:

A declarative language allows the programmer to express a structured program without having to necessarily care about the program flow. Essentially the programmer has to only care about declaring objects and letting the compiler/interpreter figure out the intended behaviour. I think it's difficult to describe, but to draw parallels, the most commonly used declarative language available today are HTML / CSS.

Built upon Javascript and JSON

Qt Quick is built upon a JSON/Javascript structure which due to its nature is very flexible dynamic language to begin with - due to lambda functions and not being strongly typed. Nevertheless javascript or it's more avoided name 'Ecmascript' has many quirks and problems; for interest see videos from Douglas Crockford - the creator of JSON. Despite many cases against for using this language in application development outside web development, it's starting to become very popular due to adavances in using JIT Interpreters.

Playing with Qt Quick using QT Creator

With the latest release of QT Creator, you don't even have to program anything. You can actually use their built in Design editor to build up the QML interface graphically. Otherwise you can code it normally. Unfortunately there is no parsing in KDevelop for QML, so you will have to resort to using QT Creator for code hints. It's very easy to set up a test application: just click new project and hit Qt Quick UI.

You'll be present with a screen with main.qml:

Make a few changes and you can then use build->run to test it out. If you're interested, you can start learning here, or wait for a few guides I may create later.

My Experiences with QML:

I have spent over a week learning and using it to build up the Render Module UI in FreeCAD. It's been relatively very good. It's very quick to learn and I was very surprised how easy it is too build an interface very quick and add some nice transition animations without having to spare too much thought. 

The convenience of JavaScript makes a lot of c++ code redundant for implementing GUI's because we can begin to use a model-view structure. This makes both programming and maintenance far easier and allows more interested program users get involved with the development of the program.

It's also giving me greater flexibility to build interfaces that are generated after the program has been run: more on this later...

Not everything is great:

The syntax can be slightly frustrating which isn't helped by the QT Creator IDE hinting. One of the big issues I am finding is the scope of functions - in javascript, when a function is called, this is binded so you have access to the previous scope. 

Nokia has pushed too much into making this into the mobile space. For example, to access mouse wheel events you have to create your own object and plug this into QML. Additionally there should be at least a repository or references for building common desktop widgets such as combo boxes just to save time and have a more unified interface. 

It's also a point that there will be inconsistency with the overall application user interface. This may not be a problem - it will later be possible to create native looking widgets:

My other complaints are that there aren't enough examples and the documentation is lacking in places which when you get stuck on something it can become slightly time consuming. 

Otherwise I would give Qt Quick a thumbs up and is heading in the right direction!

Debugging C++ using KDevelop

This is leading on from another post. Without being able to debug a program, it's very difficult to get anywhere or learn mostly from stupid mistakes and is a quintessential for making progress. Thankfully having a good IDE makes all the difference and I present to you how I use KDevelop to debug FreeCAD during development.

Debugging with KDevelop:

First ensure that you are compiling with debug symbols / information and set up KDevelop so that you can compile and launch FreeCAD successfully. Please see my previous post for information.

Open up KDevelop and then you can hit Debug.

The KDevelop workspace will now change to Debug Mode. It is more convenient to present tool panels that are more relevant to debugging than programming. The only frustration is that the Editor will not remember which file you have currently opened from the normal mode.

You can customise which tool panels are available by right clicking and selecting like so:

Useful tool panels for debugging are:

• Variables
• Breakpoints
• Frame Stack

Creating and using breakpoints using KDevelop:

FreeCAD will load, but can take slightly longer since the GDB debugger is launched and use to monitor the FreeCAD executable. Breakpoints allow you to control the flow of program at any point in time where you can:

• Pause on a line / statement (A statement is usually terminated by a semicolon, e.g. int i = 0;)
• Run each statement one by one
• Continue to the next breakpoint

By setting breakpoints, it allows the programmer to control to examine segments of code and check the behaviour of the program or complex algorithms. 

Setting a Break Point:

In the code editor window, look for an area of code that you want to examine and isolate a line where you want to pause the execution of the program. In KDevelop, click on the furthest area adjacent to the line to create a breakpoint.  KDevelop indicates when a break point is set by displaying a ladybird / ladybug.

Sometimes it is useful to set the editor to visualise the line numbers which can be done by enabling the option at Editor->View->Show Line Numbers

Now, run the program normally and attempt to 'trigger' the break point by performing an action that will cause the segment of code you want to be executed - sometimes that's not always straightforward! When a break point is hit, KDevelop will highlight this.

We have paused the execution of the program. We can control the flow by using the debug toolbar at the top.

Importantly, Step Over will run to the next statement on line 43 - this would be std::string path = hGrp...

Continue will run till it reaches the next Break Point, this could be set in the same segment of code, or in another completely different area of the program. So in the example below clicking continue would run all the program till it reaches line 48 - args.push_back(QString...

The other two I rarely use, but they will enter a function or exit a function, but often I found going directly into these function sources and setting my own break points are easier. All break points are shown in the Break Points tool view. These can be toggle on or off and can be deleted. 

*Useful hints:

• Remove all previous break points if you have recompiled FreeCAD with modifications to the code, or even just launching the program. I find it much quicker to launch FreeCAD in debug mode by doing this.
• The more editors tabs you have open, it appears to take longer to launch and consumes more memory.

Making use of Break Points:

When we stop the flow of the program, we can examine the current state of the 'stack'. KDevelop makes this exceptionally easy. We can find the current values of variables or properties of classes/objects. This can be done by highlighting over a variable or object using your cursor:

Alternatively you may use the Variables Tool View to examine all the variables accessible within the 'current scope' or on the stack. It presents a hierarchical tree and can present meaningful data for known variables types and classes within the project tree:

All it takes now is some logic and wit to figure out what is causing the problem. Sometimes it can be blindingly obvious and for other times it can take hours :( The more practice you get the easier it seems to become.

The Frame Stack:

This is most useful when you have a sudden crash.

 Conventionally a stack can be imagine like a stack of  dirty plates at a restaurant. When you enter a new program scope (e.g. run a body of a function) you add on a dirty plate (so the dirty food represents variables). Conversely, exiting a program scope you clean the plate and take off the stack of dirt dishes. I tend to imagine it like an onion, you must peel a layer to access the inner layer. 

You can view the current state of the stack using the Frame Stack Tool View, when a program crashes GDB will display the state of the frame stack to help identify where the crash occurred. This will be at Depth 0, but logically you may have to look higher up to understand why. Usually the current state of the stack variables can also be accessed using the Variables tool view. (*precaution GDB will crash if you attempt to access a null pointer)

Below the current program is on line 49 within the LuxRenderProcess::initialiseSettings method. This method was called in Renderer.cpp on line 363. It is simple as that. 

Hopefully this guide will help you get debugging and make learning how to program c++ within FreeCAD that much easier!

Render Module Updates

I have been working the past couple of days tidying things up by implementing a new Render Feature into the document tree. This further abstracts data between Renderers, so technically you make simultaneous renders providing your machine is powerful enough, assign different materials to prototype different visualisations or have different views or possible even using different Render Backends... I'm not sure about the last one, atleast regarding material selection.

U-Tube Video:

I decided it was an appropriate time to showcase some of the work that I've been doing for the past two weeks with some notes to accompany it for those interested. It hopefully shows the current state of the Render Module development for those who haven't yet tried the rendering branch. Apologies for no audio commentary, but I don't have a microphone. 

Current State:

We now have a basic UI which gives the ability to start and stop render previews and set basic options such as the output size. This also can be done through python but adds little benefit... 

Currently per RenderFeature, only one Render Process can be used, which makes sense. Buttons are disabled accordingly. 

The annoying thing with QML is that basic components such as ComboBoxes and Number Inputs don't exits - you have to create them yourselves. It's actually not bad as it sounds and slowly I'm building up a slick interface.

The Render Output preview window now works correctly. It can be scaled using the mouse wheel button and dragged around. Sadly I couldn't figure out how to zoom to cursor.

Currently it just uses a polling mechanism, but I later plan to use QFileWatcher to more intelligently check when a new output is created so we don't get LibPNG checks.

Drag and Drop Material Goodness:

This feature I'm really happy with after wrestling with the QT event system for an afternoon, the Drag & Drop material interface now works. In the screenshot above the icons are missing. 

Currently it only intends to assign materials per feature, but later this behaviour can be changed. QML however is not playing very nicely with the current task view. So I may even have to make my own sub class just so that it's contents are scaled correctly, but it would mean slight inconsistency not having the OK | CANCEL buttons unless implemented within the QML File.

So that's it for now. Still more work to do on this!

Open Cascade and Open Inventor Docs

To help with development, I've got some links to some useful documents for developing with Open Inventor and Open Cascade. These are not to be mixed up.

Coin3D / Open Inventor:

Open Inventor is a standard for 3D visualisation of scientific and engineering data. It provides a scene graph for organising and presenting data in an efficient manner. Despite being two decades old, it still provides a powerful way to develop applications. Within FreeCAD we have adopted Coin3D that provides an Open Source compatible interface for developing Open Inventor programs. There is pretty good documentation from them but there are actually no really good user guides. Two generic books were written to describe how to use and further enhance and customise Open Inventor in general:

Inventor Mentor
Inventor ToolMaker

OpenCascade:

OpenCascade provides the BREP / CSG modelling functionality within FreeCAD. It also provides many of the modelling algorithms from intersections of lines/planes to creating fillets. These two 'old' documents from an early release explain the modelling and algorithms extremely clearly with source code snippets to accompany them. 

OpenCascade Modelling Doc

OpenCascade Algorithms Doc

This tutorial provided by OpenCascade to get you started using their tools. I have yet to give this a go because I've found that the other documents provide more specific documentation in developing features.

*I am unsure what the copyright are on these but for convenience I've saved them to Google Docs. Nevertheless you can attempt to find these on google like I have done.

Using KDevelop to develop FreeCAD

Some hard core people bring themselves to use just a text editor, whether its VIM, or a standard desktop editor from Kate, GEdit. These have their places but when you're learning programming or working with large project, it's much quicker to have syntax highlighting/checking and code hinting so that you don't have to trudge through programming documentation. The additional tools for compiling make life much easier too.

One option is to look at the DOXYGEN documentation for FreeCAD. It's seldom used because its both incomplete and it's difficult to navigate without knowing what you're explicitly looking for.

For c++ programming, there are two alternatives, either QtCreator or KDevelop atleast on Linux unless someone can name some viable alternatives. Admittedly QtCreator is very good and is feature complete, for some reason it is incompatible (at least momentarily) importing projects using CMake (a build system). This essentially means you cannot read the source project tree and get useful programming hints, which without I think makes learning FreeCAD much more difficult.

Once you've installed KDevelop, it's very easy to configure the compiler settings. It's in built debugger is extraordinary especially for a newbie to diagnose crashes and above all is built in. The syntax highlighting and code hinting is generally good too. My only dissatisfaction is that sometimes it gets into the habit of crashing, but it's not a problem since it can recover unsaved files.

Here's a quick guide to help you getting it up and running to make your own opinion!

Using KDevelop to develop FreeCAD:

 Firstly ensure that KDevelop is installed and you've got a copy of the FreeCAD source to work with. Load up KDevelop as follows:

Click on Import Project to import the FreeCAD sources.

A dialog will appear. Go to the root directory within the source and then browse for the CMake project file CMakeLists.txt and click 'next'

In the next section you can specify where the FreeCAD sources are built under Build Directory. You can also set the build type. I would always recommend using the Debug build type so that you can easily debug the program for any faults later. Selecting the Release option will provide extra compiler optimisations that will improve FreeCAD's performance, but only significantly in certain areas such as the Sketch Solver. The other two options I wouldn't recommend.

Click OK and KDevelop will start importing the whole project. Further compiler and project settings can be changed under Open Configuration.

If you click under Classes tool bar you can browse the whole source tree which including other library headers. The Flying pink bricks indicate public methods. Icons with Pad Locks are 'private' class members and icons with keys are 'protected methods'.

Open  up a source file (.cpp) and try out the code hinting by pressing CONTROL + SPACEBAR. This will bring up a list of methods below which the class provides. How easy is that?

It can even help suggest the variables, objects that can be passed as arguments into a method:

Make a few little changes and the proceed to click Build Selection. 

This should start configuring your project and it may hint problems. Otherwise normally it will show the build progress in the Build Window as below:

Remember to speed up the build by using multiple cores, append -j4 under the Additional Make Options found in Project->Open Configuration->Make. Compiling usually takes between 15-25 minutes on a good day. However sit back, grab a cup of tea or continuing programming.

Finally Running FreeCAD from Kdevelop

Before running you need to configure the launches. This can be found under Run-> Configure Launches. A new dialog will appear. Choosing the executable FreeCADMain is really straightforward

Now back in the main window you can hit Execute to run normally. Alternativly you can hit Debug to run the application through the GDB debugger. I'll describe how to use the debug tools later!

Hopefully that might help you get started to make tweaks and changes to FreeCAD!

Render Appearances

Firstly kudos to NASA for landing their 1 tonne Mars Rover last night whilst us Brits were snoozing in Bed. Despite being a year of Olympics, it's looking like 2012 will be the biggest year in science/engineering for a long time.

Appearances:

Lets get back on topic. A library of materials is defined within separate XML files which are specific to each Render Plugin. In most CAD packages there are generic realistic materials such as steel, copper or brass. In the base materials library these will be defined so that you can more easily switch render plugins. These XML files can provide 'built in' or 'external' materials. External materials are essentially templates defined in separate files.  See here for an example of this proposed XML description.

These Library Materials are used for reference: FreeCAD will create a new material referencing this RenderMaterial which includes a default set of values for each parameter. These parameters can be overriden to change material properties such as the Matte colours (Kd). These render materials are later used within the Render and their properties are used to define the material. I am hoping this structure provides a more flexible approach to managing a wide variety of materials from different render plugins.

These Material Libraries can be extended by adding more XML descriptions and perhaps late in the future, users can post their materials on-line in a repository which can be universally accessed.