Use

Short version

  1. Create a Python file with a main() method that takes no arguments, and which returns your CadQuery model(s). The return type can be a single object, a list of objects, or a dictionary of names and objects. A dictionary is preferred so that you get meaningful names displayed in the viewer for your models.

  2. Run cq-studio /path/to/your/model-file.py.

  3. Point your browser at http://127.0.0.1:32323/ and view your model(s). You can select which objects to show, whether to show faces, edges, vertices, or any combination for each object, adjust transparency and other properties. You can experiment with a demo of the viewer (which comes from the YACV package) here.

  4. Edit your Python file to modify your CadQuery model(s) and save it; the changes will be pushed to the viewer in your browser.

  5. If errors are encountered (bad Python code, or CadQuery cannot handle what you’re asking it to do), they will be printed to the console where you started cq-studio, and it will then wait for the files to change again and reload them.

Use ctrl-c in the terminal you’re running cq-studio in to stop the server.

Details

The cq-studio server takes some options, which you can see using the --help option or by running it with no arguments:

Usage: cq-studio [OPTIONS] MODEL_FILE

  Copyright © 2024 Charles Cazabon <charlesc-software@pyropus.ca>.

  Licensed under the GNU General Public License v2 (only).  See the file
  COPYING for details.

Options:
  -a, --address IP-ADDRESS        listen on ADDRESS  [default: 127.0.0.1]
  -p, --port PORT                 listen on PORT  [default: 32323;
                                  1<=x<=65535]
  -i, --poll-interval INTERVAL    poll for changed files every INTERVAL
                                  seconds  [default: 1.0; 0.1<=x<=2.0]
  -o, --axes-origin / -O, --no-axes-origin
                                  show axes and orientation at origin
                                  [default: axes-origin]
  -e, --export-models / -E, --no-export-models
                                  generate STL model files from loaded objects
                                  [default: export-models]
  -l, --linear-tolerance FLOAT RANGE
                                  maximum deflection (in model units) from the
                                  ideal position for object features
                                  [default: 0.01; 1e-06<=x<=1.0]
  -A, --angular-tolerance FLOAT RANGE
                                  maximum deflection (in radians) from the
                                  ideal angle for two features  [default:
                                  0.01; 1e-06<=x<=0.1]
  -x, --exclude-dir DIR           exclude directories from watching for
                                  changes (use multiple times)  [default:
                                  .venv, .git]
  -v, --verbose                   operate more verbosely (use multiple times)
  -q, --quiet                     operate less verbosely
  --help                          Show this message and exit.

Note: the ``–address`` and ``–port`` options are provisional and can’t be used at present. While they do actually affect the address and port the server binds to, the front-end JavaScript code has the default values hardcoded, and so will only try to contact http://127.0.0.1:32323/ to obtain the models for rendering.

By default, cq-studio adds a small 3-bar object, named origin, at the (0, 0, 0) origin of the workspace to indicate the position and direction (positive) of the axes. You can suppress this be running with the --no-axes-origin option.

By default, cq-studio will export the models returned by your code to STL files in the current working directory whenever the models change. You can suppress this with the --no-export-models option. If you generally want to create model files, but not for specific model objects, you can set <object>.export_stl to False.

By default, cq-studio will print a few types of messages to the console when running, indicating when it has detected changes in the code files or modules imported by those files. You can suppress this with the --quiet option, which will result in only errors being reported on the console. Higher verbosity is generally only useful for debugging cq-studio itself.

cq-studio will ignore files (when watching for updates) under a given directory with the --exclude-dir option. This can be given multiple times to ignore more than one directory. By default, .git and .venv directories are ignored; specifying this option will override that default.

Memory/CPU Issues

The underlying CAD / solid modelling library that CadQuery (and build123d) use, Open Cascade Technology (OCCT), can run into problems with certain model features, causing that library to use extraordinary amounts of memory and CPU time. If you experience cq-studio taking extremely long times to regenerate the models after you save changes to your source files (several tens of seconds, or even more) or it appears to be allocating memory continuously without end, you can usually work around this by lowering the default tolerance values given with the --linear-tolerance/-l and --angular-tolerance/-A options.

Earlier versions of cq-studio defaulted to a value of 0.001 for these options, but that value is unnecessarily fine, and increased the probability of running into the problem. The current default is 0.01, but if you experience the problem, try setting both to 0.1 instead, which will likely prevent this behaviour.

Viewer Interface

By default, all faces/edges/vertices of the objects are shown:

The YACV (Yet Another Cad Viewer) browser interface, showing a view of the parts of a 3D printer system, with the top plate removed.

Clicking the arrow at the bottom-left of the viewer expands a control panel:

The same view as above, but with the left control panel of the YACV viewer expanded, showing the list of objects being rendered, along with controls for setting the visibility of various elements.

Clicking on the name of an object will expand controls allowing you to set transparency and other settings for that object.

For example, you can disable rendering of the faces of an object, showing only its edges and vertices, so that it is transparent:

The same view as previously, but two of the objects have had face rendering deselected, so that they are shown with only their edges rendered as lines, ghost-like, allowing what is behind them to be seen.

Another view, with the main body of the printer transparent by disabling rendering of faces on that object:

Another view with additional objects set to not render faces.

Example Project

There is an example project located in the example_project subdirectory. Run cq-server example_project/project.py and point your browser at http://127.0.0.1:32323/ .

The example project included with cq-studio looks like this:

An example CadQuery project being displayed in ``cq-studio``.  It consists of a colourful block with four screwholes at the corners, a large hole in the center with a floating sphere in the middle, and a long rod running through the sphere at an angle.  There are screws or pins floating exploded-diagram-style above the holes they fit in.

Expanding the left control panel and clicking on the block item expands the controls for that object. In addition to the face, edge, and vertex visibility toggles, there are sliders for the transparency/opacity of the object, the prominence or rendering size of its edges and vertices, and the ability to set a clipping plane anywhere on the X, Y, or Z axes.

Here you can see the block’s opacity reduced so that the sphere and rod can be seen through it:

The same model scene as above, with the colourful block object having a roughly 50% transparency value applied.