Skip to content

common.scad

Jump to bottom
Jon Gilbert edited this page Apr 24, 2024 · 1 revision

LibFile: common.scad

Common include file across openscad_annotations LibFiles

To use, add the following lines to the beginning of your file:

include <openscad_annotations/common.scad>

File Contents

  1. Section: Common Functions and Modules

Section: Common Functions and Modules

Function/Module: ok_to_annotate()

Synopsis: Determine if annotation should be done

Usage: as a function:

  • bool = ok_to_annotate();
  • bool = ok_to_annotate(<force=false>);

Usage: as a module:

  • ok_to_annotate() [CHILDREN];
  • ok_to_annotate(<force=false>) [CHILDREN];

Description:

Simplification of whether or not to produce model annotations, flyouts, or measurements.

As a function, ok_to_annotate() examines the setting of $preview, PREVIEW_ANNOTATIONS, & RENDER_ANNOTATIONS, and returns either true (meaning an annotation should be modeled) or false (meaning an annotation should not be modeled). An optional force boolean can be provided to indicate that no matter what ok_to_annotate() would have normally decided, annotation is OK; the default of force is false.

The selection of annotation behavior can be adjusted or overridden by individual SCAD models by changing PREVIEW_ANNOTATIONS from true to false, indicating that annotations should be not included during preview modes. This behavior is normally set to true, and annotations are normally modeled and displayed in preview mode.

This behavior can also be adjusted with the RENDER_ANNOTATIONS boolean, where setting it to true will cause annotations to be fully rendered and exported as STL or OBJ, or what-have-you; this is not the normal behavior.

As a module, ok_to_annotate() does the same as when invoked as a function, but instead of returning a boolean value, it processes all the child modules passed to it. The decision to process those children is exactly as if it were invoked as a function. In module form, ok_to_annotate() also accepts a force argument that will override whatever would have normally been decided.

Arguments:

By Position What it does
force Boolean that, if set to true, will ignore all other aspects and consider annotation to be OK. Default: false

PREVIEW_ANNOTATIONS is a setting that determines if annotations should be modeled when previewing models. Usually, and by default, this is enabled with true. RENDER_ANNOTATIONS is a setting that determines if annotations should be modeled when fully rendered or not. Usually, and by default, this is disabled with false. These two PREVIEW_ANNOTATIONS and RENDER_ANNOTATIONS variables exist to change this behavior from the command-line. You can set these to true or false, depending on what you need, and OpenSCAD will use them in conjuction with ok_to_annotate() when deciding if the block under the if should be produced.

Example 1: very basic usage of "should this block of modeling be executed?"

include <openscad_annotations/common.scad>
if (ok_to_annotate()) {
  // this block will be modeled, if
  // if ok_to_annotate() returned true
}



Example 2: setting RENDER_ANNOTATIONS to true on the command-line. Normally, RENDER_ANNOTATIONS is false.

include <openscad_annotations/common.scad>
$ openscad -D"RENDER_ANNOTATIONS=true"
// rendering these models will include annotations



Clone this wiki locally