added build_options to cqgi.build

cadquery/cqgi.py

@@ -75,11 +75,13 @@ class CQModel(object):
         """
         raise NotImplementedError("not yet implemented")
 
-    def build(self, build_parameters=None):
+    def build(self, build_parameters=None, build_options=None):
         """
         Executes the script, using the optional parameters to override those in the model
         :param build_parameters: a dictionary of variables. The variables must be
-        assignable to the underlying variable type.
+        assignable to the underlying variable type. These variables override default values in the script
+        :param build_options: build options for how to build the model. Build options include things like
+        timeouts, tesselation tolerances, etc
         :raises: Nothing. If there is an exception, it will be on the exception property of the result.
         This is the interface so that we can return other information on the result, such as the build time
         :return: a BuildResult object, which includes the status of the result, and either

doc/cqgi.rst

@@ -32,10 +32,26 @@ CQGI compliant containers provide an execution environment for scripts. The envi
 
  * the cadquery library is automatically imported as 'cq'.
  * the :py:meth:`cadquery.cqgi.ScriptCallback.build_object()` method is defined that should be used to export a shape to the execution environment
+ * the :py:meth:`cadquery.cqgi.ScriptCallBack.debug()` method is defined, which can be used by scripts to debug model output during execution.
 
 Scripts must call build_output at least once. Invoking build_object more than once will send multiple objects to
 the container.  An error will occur if the script does not return an object using the build_object() method.
 
+This CQGI compliant script produces a cube with a circle on top, and displays a workplane as well as an intermediate circle as debug output::
+
+    base_cube = cq.Workplane('XY').rect(1.0,1.0).extrude(1.0)
+    top_of_cube_plane = base_cube.faces(">Z").workplane()
+    debug(top_of_cube_plane, { 'color': 'yellow', } )
+    debug(top_of_cube_plane.center, { 'color' : 'blue' } )
+
+    circle=top_of_cube_plane.circle(0.5)
+    debug(circle, { 'color': 'red' } )
+
+    build_object( circle.extrude(1.0) )
+
+Note that importing cadquery is not required. 
+At the end of this script, one object will be displayed, in addition to a workplane, a point, and a circle
+
 Future enhancements will include several other methods, used to provide more metadata for the execution environment:
   * :py:meth:`cadquery.cqgi.ScriptCallback.add_error()`, indicates an error with an input parameter
   * :py:meth:`cadquery.cqgi.ScriptCallback.describe_parameter()`, provides extra information about a parameter in the script,
@@ -57,7 +73,8 @@ The :py:meth:`cadquery.cqgi.parse()` method returns a :py:class:`cadquery.cqgi.C
 Calling :py:meth:`cadquery.cqgi.CQModel.build()` returns a :py:class:`cadquery.cqgi.BuildResult` object,
 ,which includes the script execution time, and a success flag.
 
-If the script was successful, the results property will include a list of results returned by the script.
+If the script was successful, the results property will include a list of results returned by the script,
+as well as any debug the script produced
 
 If the script failed, the exception property contains the exception object.
 
@@ -67,12 +84,16 @@ with new values::
     from cadquery import cqgi
 
     user_script = ...
-    build_result = cqgi.parse(user_script).build({ 'param': 2 } )
+    build_result = cqgi.parse(user_script).build(build_parameters={ 'param': 2 }, build_options={} )
 
 If a parameter called 'param' is defined in the model, it will be assigned the value 2 before the script runs.
 An error will occur if a value is provided that is not defined in the model, or if the value provided cannot
 be assigned to a variable with the given name.
 
+build_options is used to set server-side settings like timeouts, tesselation tolerances, and other details about
+how the model should be built.
+
+
 More about script variables
 -----------------------------