Skip to main content

Drawing options and materials

bitbybit.draw.drawAnyAsync draws whatever it is given with sensible defaults. To change how something looks, pass it options: one object whose properties set the precision of the mesh, the colors of faces and edges, what is shown and what is not. The options never change the geometry, only its drawing (Geometry is not a drawing).

Each kind of entity has its own set of options, and a function that builds them with defaults for what you leave out:

EntityOptions fromRenderers
OpenCascade shapesoptionsOcctShape (every option), optionsOcctShapeSimple (the common ones), optionsOcctShapeMaterial (with an engine material)all three for the full set; the other two in BabylonJS
Manifold solids and cross sectionsoptionsManifoldShapeMaterialBabylonJS
Points, lines, polylines, curves, surfaces, JSCAD meshesoptionsSimpleall three
FramesoptionsFrameall three
The meshes of a recipeoptionsRecipeMeshesall three
Transform nodesoptionsBabylonNodeBabylonJS

In Rete, the options are a component of the draw category: connect its output to the options input of a draw component that takes the entity. In Blockly, plug the options block into the draw block's Options input. In TypeScript, create the options class, new Bit.Inputs.Draw.DrawOcctShapeOptions(), set what you need and pass it with the entity.

Here a box is drawn with see-through faces, dark edges and the index of every face and edge beside it. These are the indexes that functions picking faces and edges by number take (Picking faces and edges):

Bitbybit Platform

A shape with its faces and edges numbered in Rete

rete logoRete
Script Source (rete)
{
  "id": "rete-v2-json",
  "nodes": {
    "box": {
      "id": "box",
      "name": "bitbybit.occt.shapes.solid.createBox",
      "customName": "box",
      "async": true,
      "drawable": true,
      "data": {
        "genericNodeData": {
          "hide": true,
          "oneOnOne": false,
          "flatten": 0,
          "forceExecution": false
        },
        "width": 4,
        "length": 3,
        "height": 2,
        "center": [
          0,
          0,
          0
        ],
        "originOnCenter": true
      },
      "inputs": {},
      "position": [
        40,
        40
      ]
    },
    "options": {
      "id": "options",
      "name": "bitbybit.draw.optionsOcctShape",
      "customName": "options occt shape",
      "async": false,
      "drawable": false,
      "data": {
        "genericNodeData": {
          "hide": false,
          "oneOnOne": false,
          "flatten": 0,
          "forceExecution": false
        },
        "faceOpacity": 0.35,
        "edgeOpacity": 1,
        "edgeColour": "#1a1c1f",
        "faceColour": "#ff0000",
        "vertexColour": "#ff00ff",
        "edgeWidth": 2,
        "vertexSize": 0.03,
        "drawEdges": true,
        "drawFaces": true,
        "drawVertices": false,
        "precision": 0.01,
        "angularDeflection": 0.5,
        "relativeDeflection": false,
        "drawEdgeIndexes": true,
        "edgeIndexHeight": 0.2,
        "edgeIndexColour": "#ff00ff",
        "drawFaceIndexes": true,
        "faceIndexHeight": 0.3,
        "faceIndexColour": "#0000ff",
        "drawTwoSided": false,
        "backFaceColour": "#0000ff",
        "backFaceOpacity": 1,
        "edgeArrowSize": 0,
        "edgeArrowAngle": 15,
        "keepMeshData": false,
        "allowQualityDecrease": true,
        "forceFaceDeflection": false,
        "drawIsoCurves": false,
        "isoCurvesU": 5,
        "isoCurvesV": 5,
        "isoCurvesColour": "#808080",
        "surfaceAnalysis": "none",
        "draftDirection": [
          0,
          1,
          0
        ]
      },
      "inputs": {},
      "position": [
        40,
        380
      ]
    },
    "draw": {
      "id": "draw",
      "name": "bitbybit.draw.drawAnyAsync",
      "customName": "draw any async",
      "async": true,
      "drawable": true,
      "data": {
        "genericNodeData": {
          "hide": false,
          "oneOnOne": false,
          "flatten": 0,
          "forceExecution": false
        }
      },
      "inputs": {
        "entity": {
          "connections": [
            {
              "node": "box",
              "output": "result",
              "data": {}
            }
          ]
        },
        "options": {
          "connections": [
            {
              "node": "options",
              "output": "result",
              "data": {}
            }
          ]
        }
      },
      "position": [
        460,
        40
      ]
    }
  },
  "modules": {}
}

OpenCascade shapes​

A shape is meshed into triangles before it is drawn. precision is how far the mesh may stray from the true surface, in model units: smaller follows curves more closely and costs more triangles. Units and precision shows the difference.

In BabylonJS, ThreeJS and PlayCanvas.

OptionDefaultWhat it does
faceOpacity1How opaque the faces are, from 0 for invisible to 1 for opaque, multiplied into each look's own opacity. A faceMaterial replaces it.
edgeOpacity1How opaque the edge and iso curve lines are, from 0 for invisible to 1 for opaque.
edgeColour"#ffffff"The color of the edges, as a hex string, unless edgeContrast derives it from the faces; the edge colors of an appearance win over both.
edgeContrast-Edges take their faces' color moved toward black, or toward white on dark faces, by this amount from 0 to 1, instead of edgeColour. Appearance edge colors still win.
faceColour"#ff0000"The color of the faces, as a hex string. A faceMaterial or a surfaceAnalysis takes its place, and the colors of an appearance win over it.
vertexColour"#ff00ff"The color of the vertex markers, as a hex string; used with drawVertices.
faceMaterial-An engine material for the faces, such as draw.createPBRMaterial makes; it replaces faceColour and faceOpacity, and a surfaceAnalysis replaces it in turn.
edgeWidth2The width of the edge and iso curve lines, a hundredth of it in model units.
vertexSize0.03The diameter of the vertex markers, in model units; used with drawVertices.
drawEdgestrueWhen false, the edges are not drawn. Drawn edges or iso curves push the faces back slightly in depth so the lines show on top.
drawFacestrueWhen false, the faces and their backs are not drawn and no surfaceAnalysis is computed; the face index labels still are.
drawVerticesfalseWhen true, each vertex of the shape is drawn as a small sphere in vertexColour, vertexSize across.
precision0.01The largest distance, in model units, the triangles and edge lines may stray from the curved shape; smaller is finer and heavier.
angularDeflection0.5The largest angle, in radians, a curved face may turn between neighboring triangles; smaller follows curvature more closely with more triangles.
relativeDeflectionfalseWhen true, precision is a fraction of each edge's and face's size instead of model units, so small and large parts get triangles in proportion to their size.
drawEdgeIndexesfalseWhen true, each edge's index is written beside the middle of the edge, handy for picking edges to fillet.
edgeIndexHeight0.06The height of the edge index labels, in model units; they are drawn as lines in a plane parallel to XY.
edgeIndexColour"#ff00ff"The color of the edge index labels, as a hex string.
drawFaceIndexesfalseWhen true, each face's index is written near the middle of the face, handy for picking faces.
faceIndexHeight0.06The height of the face index labels, in model units; they are drawn as lines in a plane parallel to XY.
faceIndexColour"#0000ff"The color of the face index labels, as a hex string.
drawTwoSidedtrueWhen true, the back of each face is drawn in backFaceColour, which shows which way faces point. A design build draws no backs.
backFaceColour"#0000ff"The color of the back of the faces, as a hex string; used with drawTwoSided.
backFaceOpacity1How opaque the back of the faces is, from 0 for invisible to 1 for opaque; used with drawTwoSided.
edgeArrowSize0The length of an arrow head at the end of each edge, showing its direction, in model units; 0 draws none.
edgeArrowAngle15The angle, in degrees, between each line of an arrow head and its edge; larger spreads the head wider.
keepMeshDatafalseWhen true, the triangulation stays cached on each shape after drawing; when false it is cleared so memory does not grow across draws.
allowQualityDecreasetrueWhen true, a shape already meshed more finely may be remeshed at the coarser precision asked for.
forceFaceDeflectionfalseWhen true, every face is remeshed at the requested precision even when a triangulation is cached.
drawIsoCurvesfalseWhen true, each face's iso curves are drawn with the shape, as its edges are: at edgeWidth and edgeOpacity, in isoCurvesColour.
isoCurvesU5How many iso curves of constant u each face gets with drawIsoCurves, at values spread evenly inside its u range and trimmed to the face.
isoCurvesV5How many iso curves of constant v each face gets with drawIsoCurves, at values spread evenly inside its v range and trimmed to the face.
isoCurvesColour"#808080"The color of the iso curves as a hex string.
surfaceAnalysis"none"The surface analysis coloring the faces instead of faceColour and faceMaterial, from blue at analysisMin through green to red at analysisMax; vertices without a value keep faceColour.
draftDirection[0, 1, 0]The pull direction the draft angles, in degrees, are measured against; read only when surfaceAnalysis is draftAngle.
analysisMin-The analysis value drawn blue, and anything below it; left out, the lowest finite value found.
analysisMax-The analysis value drawn red, and anything above it; left out, the highest finite value found.

The common options only​

In BabylonJS.

OptionDefaultWhat it does
precision0.01The largest distance, in model units, the triangles and edge lines may stray from the curved shape; smaller is finer and heavier.
drawFacestrueWhen false, the faces and their backs are not drawn.
faceColour"#ff0000"The color of the faces, as a hex string.
drawEdgestrueWhen false, the edges are not drawn.
edgeColour"#ffffff"The color of the edges, as a hex string.
edgeWidth2The width of the edge and iso curve lines, a hundredth of it in model units.
drawTwoSidedtrueWhen true, the back of each face is drawn in backFaceColour, which shows which way faces point.
backFaceColour"#0000ff"The color of the back of the faces, as a hex string; used with drawTwoSided.
backFaceOpacity1How opaque the back of the faces is, from 0 for invisible to 1 for opaque; used with drawTwoSided.

With an engine material​

In BabylonJS.

OptionDefaultWhat it does
precision0.01The largest distance, in model units, the triangles and edge lines may stray from the curved shape; smaller is finer and heavier.
faceMaterial-The engine material the faces are drawn with, such as draw.createPBRMaterial makes; it sets their color and opacity.
drawEdgestrueWhen false, the edges are not drawn.
edgeColour"#ffffff"The color of the edges, as a hex string.
edgeWidth2The width of the edge and iso curve lines, a hundredth of it in model units.

Manifold solids and cross sections​

In BabylonJS.

OptionDefaultWhat it does
faceOpacity1How opaque the faces are, from 0 for invisible to 1 for opaque; a faceMaterial replaces it.
faceColour"#ff0000"The color of the faces of solids and meshes, as a hex string; a faceMaterial replaces it.
faceMaterial-An engine material for the faces, such as draw.createPBRMaterial makes; given, it replaces faceColour and faceOpacity.
crossSectionColour"#ff00ff"The color of the outline of a cross-section, as a hex string.
crossSectionWidth2The width of the outline of a cross-section, a hundredth of it in model units.
crossSectionOpacity1How opaque the outline of a cross-section is, from 0 for invisible to 1 for opaque.
computeNormalstrueWhen true, the mesh shades smoothly across edges flatter than minSharpAngle and keeps sharper ones crisp; when false, every face is shaded flat.
minSharpAngle40The angle between two faces, in degrees, above which their shared edge is drawn sharp when computeNormals is true.
drawTwoSidedtrueWhen true, the back of the faces of solids and meshes is drawn in backFaceColour, which shows which way they face.
backFaceColour"#0000ff"The color of the back of the faces, as a hex string; used with drawTwoSided.
backFaceOpacity1How opaque the back of the faces is, from 0 for invisible to 1 for opaque; used with drawTwoSided.

Points, lines, curves and meshes​

In BabylonJS, ThreeJS and PlayCanvas.

OptionDefaultWhat it does
colours"#ff0000"One hex color for everything drawn, or a list with one per point, line, polyline, surface or JSCAD mesh; a polyline or JSCAD mesh with its own color keeps it.
colorMapStrategy"lastColorRemainder"How a colours list shorter than what is drawn is spread: first color for all, last for the rest, repeating, or back and forth. JSCAD meshes and curves ignore it.
size0.1The diameter of each point in model units and the width of lines, a hundredth of it in model units. Lines drawn without options get 2.
opacity1The opacity of points, lines, surfaces and JSCAD meshes, from 0 for invisible to 1 for opaque.
updatablefalseWhen true, handing the drawn object back as babylonMesh changes it in place instead of drawing a new one.
hiddenfalseWhen true, surfaces and JSCAD meshes are drawn but not shown until made visible; points and lines ignore it.
drawTwoSidedtrueWhen true, the back of each surface and JSCAD mesh is drawn in backFaceColour, which shows which way it faces.
backFaceColour"#0000ff"The color of the back of surfaces and JSCAD meshes, as a hex string; used with drawTwoSided.
backFaceOpacity1How opaque the back of surfaces and JSCAD meshes is, from 0 for invisible to 1 for opaque; used with drawTwoSided.
arrowSize0The length of the arrow head at the end of each line and polyline, showing its direction, in model units; 0 draws none.
arrowAngle15The angle, in degrees, between each line of an arrow head and the line it ends; larger spreads the head wider.

Frames​

In BabylonJS, ThreeJS and PlayCanvas.

OptionDefaultWhat it does
size1Length of each axis, in model units; the grid in the plane is as wide, centered on the origin.
colorX"#ff0000"Color of the X axis, which runs along the frame's direction.
colorY"#00ff00"Color of the Y axis.
colorZ"#0000ff"Color of the Z axis, which runs along the frame's normal.
drawPlanetrueWhether to draw the small grid in the frame's plane around its origin.
colorPlane"#808080"Color of the grid in the frame's plane.
lineWidth2The width of the axis and grid lines, a hundredth of it in model units.
updatablefalseWhen true, handing the drawn frame back as babylonMesh changes it in place instead of drawing a new one.

The meshes of a recipe​

In BabylonJS, ThreeJS and PlayCanvas.

OptionDefaultWhat it does
elementKey"globalId"The tag whose value names an element, so the roots sharing it show, hide, color and pick as one.
instancingtrueWhen true, a mesh placed often enough by matrices that only turn and move is drawn as instances, one draw call for all of them.
minInstances2How many such placements of one mesh make it instances.
maxBatchVertices1000000The most vertices one merged batch holds; more start another batch.
defaultColour"#cccccc"The color of a root whose tag has no rgba.
defaultOpacity1The opacity of such a root, from 0 to 1.
metallic0How metallic every surface is, from 0 to 1.
roughness0.8How rough every surface is, from 0 to 1.

Transform nodes​

In BabylonJS.

OptionDefaultWhat it does
colorX"#ff0000"The color of the line along the node's X axis, as a hex string.
colorY"#00ff00"The color of the line along the node's Y axis, as a hex string.
colorZ"#0000ff"The color of the line along the node's Z axis, as a hex string.
size2The length of each axis line in the node's own space, so a scaled node scales its axes too.

Materials and textures​

A color is enough for most drawings. For metal, glass, a glowing part or an image on a surface, make a material with createPBRMaterial and put it in the faceMaterial of the options. Its settings mean the same in all three renderers. createTexture loads an image from a URL for the material's texture slots. Materials, colour and the look shows a metal sphere built this way.

In BabylonJS, ThreeJS and PlayCanvas.

OptionDefaultWhat it does
name"PBRMaterial"The name the engine gives the material.
baseColor"#0000ff"The base color of the surface, as a hex string.
metallic0.5How metallic the surface is, from 0 for plastic-like to 1 for metal.
roughness0.5How rough the surface is, from 0 for a mirror-like shine to 1 for a matte finish.
alpha1How opaque the material is, from 0 for invisible to 1 for opaque; the default opaque mode of alphaMode ignores it and blend shows it.
emissiveColor"#000000"The color the surface glows with whatever the scene's lights, as a hex string; black, the default, adds no glow.
emissiveIntensity1How strongly the surface glows: the emissive color is multiplied by it.
zOffset0Not read by this renderer; its materials keep no depth offset.
zOffsetUnits0Not read by this renderer; its materials keep no depth offset.
baseColorTexture-An image from draw.createTexture for the base color of the surface.
metallicRoughnessTexture-An image holding metallic in its blue channel and roughness in its green channel, as glTF lays them out.
normalTexture-A normal map, which adds surface detail by bending the lighting without changing the geometry.
emissiveTexture-An image giving where and in which color the surface glows.
occlusionTexture-An ambient occlusion map, which darkens the creases and corners light reaches less.
alphaMode"opaque"How opacity is applied: opaque ignores it, mask cuts away pixels below alphaCutoff, and blend draws the faces see-through.
alphaCutoff0.5The opacity below which a pixel is cut away; used with alphaMode set to mask.
doubleSidedfalseWhen true, both sides of each face are drawn; when false, the back is culled.
wireframefalseNot read by this renderer; the faces are drawn filled whatever the value.
unlitfalseWhen true, the scene's lights are ignored and the surface shows its colors flat.

Textures​

In BabylonJS, ThreeJS and PlayCanvas.

OptionDefaultWhat it does
url-Where the image is loaded from, as a path relative to the page or a full web address.
name"Texture"The name the engine gives the texture.
uScale1How many times the image repeats along U, the first texture direction of the surface; 0 counts as 1.
vScale1How many times the image repeats along V, the second texture direction of the surface; 0 counts as 1.
uOffset0How far the image is shifted along U, in image widths.
vOffset0How far the image is shifted along V, in image heights.
wAng0How far the image is turned on the surface, in radians.
invertYfalseWhen true, the image is flipped vertically as it loads; false, the default, keeps its rows in file order.
invertZfalseNot read by this renderer; the image keeps its orientation whatever the value.
samplingMode"nearest"How the image is sampled when shown larger or smaller than its pixels: nearest keeps hard pixels, bilinear blends neighbors, and trilinear also blends between mipmap levels.

Every function​

FunctionWhat it does
createPBRMaterialCreates a physically based material from settings that mean the same in every renderer: base color, metallic and roughness, opacity, emissive glow, the texture slots and the alpha and side options; put it in the faceMaterial of the drawing options.
createTextureCreates an image texture from a URL for the texture slots of createPBRMaterial, with tiling, offset, rotation and filtering that mean the same in every renderer.
detectNodeWhether the entity is a node this renderer can draw an axis triad for.
detectNodes
drawAnyDraws an entity that needs no kernel work into the scene right away and gives back the drawn object: points, lines, polylines, frames, tags and nodes.
drawAnyAsyncDraws any entity the library produces into the scene and gives back the drawn object: kernel shapes, alone or with their appearance, design builds, points, lines, polylines, frames, curves, meshes, tags and nodes.
drawAnyAsyncNoReturnDraws any entity into the scene, as drawAnyAsync does, without giving the drawn object back; for the last step of a script that only needs the result to appear.
drawAnyNoReturnDraws an entity that needs no kernel work, as drawAny does, without giving the drawn object back; points, lines, polylines, frames and tags qualify, kernel shapes do not.
drawGridMeshDraws a grid on the ground plane, the XZ plane through the origin, to give a sense of scale and orientation; every tenth line is drawn thicker by default.
drawGridMeshNoReturnDraws a grid on the ground plane, as drawGridMesh does, without giving the mesh back.
node.createNodeFromRotationCreates a node at origin turned by the three rotation angles in degrees around X, Y and Z, inside the coordinate system of parent when one is given.
node.createWorldNodeCreates a node parented to the root node of the scene, a fresh starting point for building a hierarchy at the world origin.
node.drawNodeDraws the three axes of a node as colored lines of the given length, parented to it, so its position and orientation can be seen; the default colors are red for X, green for Y and blue for Z.
node.drawNodesDraws the three axes of several nodes as colored lines of the given length, each set parented to its node, as drawNode does for one.
node.getAbsoluteForwardVectorReads the direction a node's local Z axis points in world space, with every parent's rotation applied.
node.getAbsolutePositionReads where a node's origin is in world space, with every parent's transform applied.
node.getAbsoluteRightVectorReads the direction a node's local X axis points in world space, with every parent's rotation applied.
node.getAbsoluteRotationTransformationReads the rotation of a node in world space, with every parent's rotation applied, as a 4x4 matrix of 16 numbers.
node.getAbsoluteUpVectorReads the direction a node's local Y axis points in world space, with every parent's rotation applied.
node.getChildrenLists the nodes and meshes parented directly under a node, the ones that move with it.
node.getParentReads the node a node is parented to, the one it moves with; a top-level node has none.
node.getPositionExpressedInLocalSpaceReads a node's position measured in its own local axes rather than its parent's, which differs once the node is rotated.
node.getRootNodeGives the root node of the scene, the top of the hierarchy that createWorldNode parents to.
node.getRotationReads a node's rotation relative to its parent as three angles in degrees around X, Y and Z.
node.getRotationTransformationReads the rotation of a node relative to its parent as a 4x4 matrix of 16 numbers; the node must carry a rotation quaternion, which rotate and setDirection give it.
node.rotateTurns a node by angle degrees around an axis through its own origin, on top of its current rotation; its children follow.
node.rotateAroundAxisWithPositionTurns a node by angle degrees around an axis that passes through position, so the node orbits that point rather than spinning in place; its children follow.
node.setAbsolutePositionMoves a node to a point in world space, whatever its parents are; its children follow.
node.setDirectionTurns a node so its local Z axis points along direction; its children follow.
node.setParentParents a node to another so it moves with it from then on, keeping its current place in the world; a null parent detaches it.
node.translateMoves a node by distance scene units along direction, given in the node's own local axes; its children follow.
optionsBabylonNodeBuilds drawing options for transform nodes, which are drawn as a triad of colored axis lines of a given length.
optionsFrameBuilds drawing options for frames: how long the axes are and their colors, whether the small grid in the frame's plane is drawn and in which color, the line width and whether the frame can be redrawn in place, with defaults for what is left out.
optionsManifoldShapeMaterialBuilds drawing options for Manifold solids and cross-sections: face color or a full engine material, the line style of cross-sections, normals and the two-sided rendering.
optionsOcctShapeBuilds the full drawing options for OCCT shapes: meshing precision, face, edge and vertex colors and sizes, index labels, arrows on edges, two-sided rendering, iso curves, a surface analysis coloring the faces and the triangulation cache, with defaults for what is left out.
optionsOcctShapeMaterialBuilds drawing options for OCCT shapes whose faces use a full engine material, as createPBRMaterial makes one, plus the precision and edge style.
optionsOcctShapeSimpleBuilds the most used drawing options for OCCT shapes, precision, face and edge colors and two-sided rendering, with defaults for what is left out.
optionsRecipeMeshesBuilds drawing options for the meshes of a recipe, as manifold.recipes.meshes gives them: the tag naming an element, when repeated meshes become instances, the batch size, and the color and surface of roots without a color.
optionsSimpleBuilds drawing options for points, lines, polylines, curves, surfaces and JSCAD meshes: colors, size, opacity, two-sided rendering and arrow heads on lines, with defaults for what is left out.
recipeElementOfPickGives the element a pick hit in a recipe drawn from its meshes, as the value of its element tag, from the mesh and the face or thin instance the scene's pick reports.
setRecipeElementsColourShows elements of a recipe drawn from its meshes in one color, such as the ones selected, or with no color gives each its own back, by the values of their element tag.
setRecipeElementsVisibleShows or hides elements of a recipe drawn from its meshes, such as one storey's walls, by the values of their element tag, changing only their own triangles and instances.
tag.createBuilds a tag description from its text, position, color, size and depth behavior, without drawing it; drawTag or drawTags put it on screen.
tag.drawTagPuts one tag on screen as a text element pinned to its 3D position, and keeps it following that position.
tag.drawTagsPuts several tags on screen, each a text element pinned to its 3D position.