Skip to content

Latest commit

 

History

History
192 lines (133 loc) · 8.6 KB

README.md

File metadata and controls

192 lines (133 loc) · 8.6 KB
Raw

Renderers plug-ins

This is the renderers plug-ins directory.

How FreeCAD-render works with external renderers

To obtain a rendering, given a specific external renderer, FreeCAD-render writes a file (the input file) in renderer format and runs the external renderer on this file. As a result, the external renderer outputs an image file.

The input file is written in a so-called Scene Description Language (SDL), which is specific to the renderer.

FreeCAD-render builds the input file by instantiating a template with descriptions of FreeCAD objects in renderer SDL:

  • The template basically contains placeholders sections to be filled with objects descriptions, following the general structure expected by the renderer, and also contains predefined settings designed for given use cases: standard scene, sunlight scene...
  • The objects descriptions in renderer SDL are generated by ad hoc plug-ins.

How to add support for a new external renderer

Files required

To add support for a new renderer, you will need to add at least 3 files:

  • A renderer plug-in module,
  • An icon file,
  • One or more templates file(s),
Files Number Location File format
Renderer plug-in 1 This directory Python
Icon 1 ../icons Image (png, svg...)
Templates 1 or more ../templates Your renderer format

Optionally, but in a strongly recommended way, you will also add a few entries in module's Preferences. In particular, it is strongly recommended to include the following parameters:

  • the path to the external renderer executable (optionally split into CLI and GUI executable paths, if the renderer provides both),
  • the renderer command line parameters.

Renderer plug-in

Naming

You need to make sure your plugin file is named with the same name (case sensitive) that you will use everywhere to describe your renderer.

This name must start with a capital letter, and have a '.py' extension.

Examples: Appleseed.py or Povray.py

Valid plugins are collected in Render.RENDERERS constant (in Render.py) at workbench initialization. In case of trouble, you can check this variable to debug your naming.

Contents

The plugin must contain the following functions:

  • write_mesh(name, mesh, material, **kwargs)

    Expected behaviour: Return a string containing a mesh object description in renderer SDL

    Input parameters:

    Parameter Type Description
    name str Object name
    mesh Mesh.Mesh (Mesh::Feature) Mesh description
    material material.Material Rendering material

     

  • write_camera(name, pos, up, target, **kwargs)

    Expected behaviour: Return a string containing a camera description in renderer SDL

    Input parameters:

    Parameter Type Description
    name str Camera name
    pos FreeCAD.Placement Camera placement (origin & rotation)
    up FreeCAD.Vector Camera up direction
    target FreeCAD.Vector Camera target direction
    fov float Camera field of view, in degrees

     

  • write_pointlight(name, pos, color, power, **kwargs)

    Expected behaviour: Return a string containing a point light description in renderer SDL

    Input parameters:

    Parameter Type Description
    name str Point light name
    pos App.Vector Point light position
    color tuple (3 floats) RGB color of the point light
    power float Power of the point light

     

  • write_arealight(name, pos, size_u, size_v, color, power, kwargs)

    Expected behaviour: Return a string containing an area light description in renderer SDL

    Input parameters:

    Parameter Type Description
    name str Area light name
    pos App.Placement Area light placement (origin & rotation)
    size_u int Width of the area light
    size_v int Height of the area light
    color tuple (3 floats) RGB color of the area light
    power float Power of the area light

     

  • write_imagelight(name, image, **kwargs)

    Expected behaviour: Return a string containing an image-based light description in renderer SDL

    Input parameters:

    Parameter Type Description
    name str Image light name
    image str Image light file path

     

  • render(project, prefix, external, output, width, height)

    Expected behaviour: Generate a command to render the given project. The command is meant to be executed by the framework. This function is in charge of writing the renderer input file and building the system command to call the renderer upon the input file.

    Input parameters:

    Parameter Type Description
    project Render.Project Project to render
    prefix str A prefix string for call (to be inserted before path to renderer)
    external bool A flag indicating whether to call UI (true) or console (false) version of renderer
    output str Output file name
    width int Output width, in pixels
    height int Output height, in pixels

    Outputs:

    • The command to run in order to call the renderer executable
    • The path to the future image file to be generated by the renderer

    In case the path to renderer is empty, (None, None) should be returned.

     

The plugin should also define the following constant:

  • TEMPLATE_FILTER

    Expected value: a string describing the file filter for the renderer's templates. The format of the string is the same as the one used by QFileDialog.getOpenFileName in PySide2 library (see here) Please note there is no need to add the generic All files (*.*) filter, as it is automatically appended.

    Example: TEMPLATE_FILTER = "Appleseed templates (appleseed_*.appleseed)"

     

Guidelines

  • Before writing a new plug-in, have a look at other existing renderers plug-ins. You can use one of them as a template for a new plugin
  • Use Python's Format Specification Mini Language in write_* functions to build SDL strings (avoid concatenation approach).
  • Carefully read your renderer documentation, especially the Scene Description Language chapters. For future reviewing, do not hesitate to add links to the documentation in your code, as comments.
  • Pay attention to the coordinates systems. External renderers may use different coordinates than FreeCAD (inverted coordinates etc.)

Templates

Naming

The name of the file should contain a reference to your renderer, and then a reference to the use case which the template addresses. The file extension should be the extension expected by the renderer in its input file. Example: appleseed_standard.appleseed

Icon file

Naming

The name of the icon file should be the same as the plug-in file. Example: Appleseed.svg.

Recommended icon format is Scalable Vector Graphics (SVG).

Preferences

Preferences settings are implemented in ui/RenderSetting.ui file