# 67. `plugins.webgl` — View and manipulate 3D models in your browser.

This module defines some classes and function to help with the creation of WebGL models. A WebGL model can be viewed directly from a compatible browser (see http://en.wikipedia.org/wiki/WebGL).

A WebGL model typically consists out of an HTML file and a Javascript file, possibly also some geometry data files. The HTML file is loaded in the browser and starts the Javascript program, responsible for rendering the WebGL scene.

class `plugins.webgl.``WebGL`(name='Scene1', scripts=None, bgcolor='white', title=None, description=None, keywords=None, author=None, htmlheader=None, jsheader=None, pgfheader=None, sep='', dataformat='.pgf.gz', urlprefix=None, gui=True, cleanup=False)

  A class to export a 3D scene to WebGL.

  Exporting a WebGL model creates:

  - a HTML file calling some Javascript files. This file can be viewed in a WebGL enabled browser (Firefox, Chrome, Safari)
  - a Javascript file describing the model. This file relies an other Javascript files to do the actual rendering and provide control menus. The default rendering script is https://net.feops.com/public/webgl/fewgl-0.2.js and the gui toolkit is https://net.feops.com/public/webgl/xtk_xdat.gui.js. The user can replace them with scripts of his choice.
  - a number of geometry files in pyFormex PGF format. These are normally created automatically by the exportScene method. The user can optionally add other files.

  An example of its usage can be found in the WebGL example.

  Parameters:

  - name: string: the base name for the created HTML and JS files.
  - scripts: a list of URLs pointing to scripts that will be needed for the rendering of the scene.
  - bgcolor: string: the background color of the rendered page. This can be the name of a color or a hexadecimal WEB color string like ‘#F0A0F0’.
  - title: string: an optional title to be set in the .html file. If not specified, the name is used.
  - description, keywords, author: strings: if specified, these will be added as meta tags to the generated .html file. The first two have defaults if not specified.
  - htmlheader: string: a string to be included in the header section of the exported html file. It should be al legal html string.
  - jsheader: string: a string to be included at the start of the javascript file. It should be a legal javascript text. Usually, it is only used to insert comments, in which case all lines should start with ‘//’, or the whole text should be included in a ‘/’, ‘/’ pair.
  - dataformat: string: the extension of the data files used for storing the geometry. This should be an extension supported by the webgl rendering script. The default (https://net.feops.com/public/webgl/fewgl-0.2.js”) will always support pyFormex native formats ‘.pgf’ and ‘.pgf.gz’. Some other formats (like .stl) may also be supported, but the use of the native formats is prefered, because they are a lot smaller. Default is to use the compressed ‘.pgf.gz’ format.
  - urlprefix: string: if specified, this string gets prepended to the exported .js filename in the .html file, and to the datafiles in the exported .js file. This can be used to serve the models from a web server, where the html code is generated dynamically and the model script and data can not be kept in the same location as the html.
  - gui: bool: if True, a gui will be added to the model, allowing some features to be changed interactively.
  - cleanup: bool: if True, files in the output directory (the current work directory) starting with the specified base name and having a name structure used by the exported, will be deleted from the file system. Currently, this includes files with name patterns NAME.html*, NAME.js* NAME_*.pgf* and NAME_*.stl*.
  `addScene`(name=None, camera=True)

    Add the current OpenGL scene to the WebGL model.

    This method adds all the geometry in the current viewport to the WebGL model. By default it will also add the current camera and export the scene as a completed WebGL model with the given name.

    Parameters:

    - name: a string with the name of the model for the current scene. When multiple scenes are exported, they will be identified by this name. This name is also used as the basename for the exported geometry files. For a single scene export, the name may be omitted, and will then be set equal to the name of the WebGL exporter. If no name is specified, the model is not exported. This allows the user to add more scenes to the same model, and then to explicitely export it with `exportScene()`.
    - camera: bool or dict : if True, sets the current viewport camera as the camera in the WebGL model. If False the default camera values of WebGL will be used. If dict the camera values will be taken from the dictionary.
  `addActor`(actor)

    Add an actor to the model.

    The actor’s drawable objects are added to the WebGL model as a list. The actor’s controller attributes are added to the controller gui.

  `setCamera`(**kargs)

    Set the camera position and direction.

    This takes two (optional) keyword parameters:

    - position=: specify a list of 3 coordinates. The camera will be positioned at that place, and be looking at the origin. This should be set to a proper distance from the scene to get a decent result on first display.
    - upvector=: specify a list of 3 components of a vector indicating the upwards direction of the camera. The default is [0.,1.,0.].
  `format_actor`(actor)

    Export an actor in Javascript format for fewgl.

  `format_gui_controller`(name, attr)

    Format a single controller

  `format_gui`()

    Create the controller GUI script

  `start_js`(name)

    Export the start of the js file.

    Parameters:

    - name: string: the name of the model that will be shown by default when displaying the webgl html page

    This function should only be executed once, before any other export functions. It is called automatically by the first call to exportScene.

  `exportScene`(name=None)

    Export the current OpenGL scene to the WebGL model.

    Parameters:

    - name: string: the name of the model in the current scene. When multiple scenes are exported, they will be identified by this name. This name is also used as the basename for the exported geometry files. For a single scene export, the name may be omitted, and will then be set equal to the name of the WebGL exporter.
  `export`(body='', createdby=-1)

    Finish the export by creating the html file.

    Parameters:

    - body: an HTML section to be put in the body
    - createdby: int. If not zero, a logo ‘Created by pyFormex’ will appear on the page. If > 0, it specifies the width of the logo field. If < 0, the logo will be displayed on its natural width.

    Returns the full path of the create html file.

## 67.1. Functions defined in module plugins.webgl

`plugins.webgl.``saneSettings`(k)

  Sanitize sloppy settings for JavaScript output

`plugins.webgl.``properties`(o)

  Return properties of an object

  properties are public attributes (not starting with an ‘_’) that are not callable.

`plugins.webgl.``createdBy`(width=0)

  Return a div html element with the created by pyFormex logo

`plugins.webgl.``createWebglHtml`(name, scripts=[], bgcolor='white', body='', description='WebGL model', keywords='pyFormex, WebGL', author='', title='pyFormex WebGL model', header='')

  Create a html file for a WebGL model.

  Returns the absolute pathname to the created HTML file.

`plugins.webgl.``surface2webgl`(S, name, caption=None)

  Create a WebGL model of a surface

  - S: TriSurface
  - name: basename of the output files
  - caption: text to use as caption

`plugins.webgl.``createMultiWebGL`()

  Creates a multimodel WebGL from single WebGL models