Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fixed improper handling of string parameters #31

Merged
merged 2 commits into from
Feb 10, 2024
Merged

Fixed improper handling of string parameters #31

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dca4654
Fixed improper handling of string arguments
jmwright Feb 10, 2024
7a93bed
Updated the readme for string parameters and fixed some other things …
jmwright Feb 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 39 additions & 39 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,10 @@

## Introduction

***Please Note*** cq-cli is in alpha currently. Major features may be broken, and the application may change a lot before a full release.
***Please Note*** cq-cli is in beta.

cq-cli is a Command Line Interface for executing CadQuery scripts and converting their output to another format. It uses a plugin system where "codecs" can be placed in the cqcodecs directory and will be automatically loaded and used if a user selects that codec from the command line.

cq-cli is designed to be a batteries-included distribution, although this approach comes with some drawbacks as listed below. However, to have a CadQuery conversion utility that requires no installation and no Anaconda environment can be useful in certain cases.

It is possible to specify input and output files using arguments, but cq-cli also allows the use to the stdin, stdout and stderr streams so that it can be used in a pipeline.

Linux, MacOS and Windows are supported, but some features may be used differently or may not work the same in Windows.
Expand Down Expand Up @@ -51,11 +49,17 @@ python -m cq_cli.main --help

## Installation (Stand-Alone)

Download a binary distribution that is appropriate for your operating system from the [latest release](https://github.com/CadQuery/cq-cli/releases/tag/v0.1.0-alpha), extract the zip file, and make sure to put the cq-cli binary in the PATH. Then the CLI can be invoked as `cq-cli` (`cq-cli.exe` on Windows).
**Please note:** This method is not recommended now that cq-cli can be installed via pip, but it is still an option if it is not possible to use a Python virtual environment.

Download a binary distribution that is appropriate for your operating system from the [latest PyInstaller workflow run with a green checkmark](https://github.com/CadQuery/cq-cli/actions/workflows/pyinstaller.yml), extract the zip file, and make sure to put the cq-cli binary in the PATH. Then the CLI can be invoked as `cq-cli` (`cq-cli.exe` on Windows).

If installing on Windows, the [latest redistributable for Visual Studio](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads) will need to be installed.

If a development installation is desired, see the [Contributing](#contributing) section below.

## Drawbacks of Stand-Alone Installation

* The file (and directory) size for cq-cli is very large. cq-cli uses pyinstaller to package the binaries for each platform, and must embed all needed dependencies. The OCP and OCCT library dependencies add a minimum of ~270 MB of data on top of the included Python distribution. It is possible that the pyinstaller spec file could be optimized. If you are interested in helping with this, please let us know by opening an issue.
* Startup times for the single binary are relatively slow. If startup and execution time is important to you, consider using the pyinstaller_dir.spec spec file with pyinstaller: `pyinstaller pyinstaller_dir.spec`.

## Usage

Expand All @@ -64,82 +68,78 @@ usage: cq-cli.py [-h] [--codec CODEC] [--infile INFILE] [--outfile OUTFILE] [--e
Command line utility for converting CadQuery script output to various other output formats.

optional arguments:
* -h, --help Show this help message and exit
* --codec CODEC The codec to use when converting the CadQuery output. Must match the name of a codec file in the cqcodecs directory.
* --getparams GETPARAMS
* --infile INFILE The input CadQuery script to convert.
* --outfile OUTFILE File to write the converted CadQuery output to. Prints to stdout if not specified.
* --errfile ERRFILE File to write any errors to. Prints to stderr if not specified.
* --params PARAMS A colon and semicolon delimited string (no spaces) of key/value pairs representing variables and their values in the CadQuery script. i.e. var1:10.0;var2:4.0;
* --outputopts OPTS A colon and semicolon delimited string (no spaces) of key/value pairs representing options to pass to the selected codec. i.e. width:100;height:200;
* --validate VALIDATE Setting to true forces the CLI to only parse and validate the script and not produce converted output.
* `-h`, `--help` Show this help message and exit
* `--codec` CODEC The codec to use when converting the CadQuery output. Must match the name of a codec file in the cqcodecs directory.
* `--getparams` GETPARAMS
* `--infile` INFILE The input CadQuery script to convert.
* `--outfile` OUTFILE File to write the converted CadQuery output to. Prints to stdout if not specified.
* `--errfile` ERRFILE File to write any errors to. Prints to stderr if not specified.
* `--params` PARAMS A colon and semicolon delimited string (no spaces) of key/value pairs representing variables and their values in the CadQuery script. i.e. var1:10.0;var2:4.0;
* `--outputopts` OPTS A colon and semicolon delimited string (no spaces) of key/value pairs representing options to pass to the selected codec. i.e. width:100;height:200;
* `--validate` VALIDATE Setting to true forces the CLI to only parse and validate the script and not produce converted output.

## Examples

1. Find out what codecs are available.
```
./cq-cli.py --codec help
cq-cli --codec help
```
2. Validate a CadQuery script.
```
./cq-cli.py --validate true --infile /input/path/script.py
cq-cli --validate true --infile /input/path/script.py
```
3. Convert a CadQuery script to STEP format and output to stdout.
```
./cq-cli.py --codec step --infile /input/path/script.py
cq-cli --codec step --infile /input/path/script.py
```
4. Convert a CadQuery script to STEP format and write to a file.
```
./cq-cli.py --codec step --infile /input/path/script.py --outfile /output/path/newfile.step
cq-cli --codec step --infile /input/path/script.py --outfile /output/path/newfile.step
```
5. Convert a CadQuery script and write any errors to a separate file.
```
./cq-cli.py --codec step --infile /input/path/script.py -errfile /error/path/error.txt
cq-cli --codec step --infile /input/path/script.py -errfile /error/path/error.txt
```
6. Convert a CadQuery script using the stdin and stdout streams. This example counts the lines in the resulting STEP output as a trivial example.
```
cat /input/path/script.py | cq-cli.py --codec step | wc -l
```
7. Convert a CadQuery script to SVG, passing in output options to influence the resulting image.
```
./cq-cli.py --codec svg --infile /input/path/script.py --outfile /output/path/newfile.svg --outputopts "width:100;height:100;marginLeft:12;marginTop:12;showAxes:False;projectionDir:(0.5,0.5,0.5);strokeWidth:0.25;strokeColor:(255,0,0);hiddenColor:(0,0,255);showHidden:True;"
cq-cli --codec svg --infile /input/path/script.py --outfile /output/path/newfile.svg --outputopts "width:100;height:100;marginLeft:12;marginTop:12;showAxes:False;projectionDir:(0.5,0.5,0.5);strokeWidth:0.25;strokeColor:(255,0,0);hiddenColor:(0,0,255);showHidden:True;"
```
8. Convert a CadQuery script to STL, passing in output options to change the quality of the resulting STL. Explanation of linear vs angular deflection can be found [here](https://dev.opencascade.org/doc/occt-7.1.0/overview/html/occt_user_guides__modeling_algos.html#occt_modalg_11_2).
```
./cq-cli.py --codec stl --infile /input/path/script.py --outfile /output/path/script.stl --outputopts "linearDeflection:0.3;angularDeflection:0.3"
cq-cli --codec stl --infile /input/path/script.py --outfile /output/path/script.stl --outputopts "linearDeflection:0.3;angularDeflection:0.3"
```
9. Extract parameter information from the input script. The outfile argument can also be left off to output the parameter JSON to stdout.
```
./cq-cli.py --getparams /output/path/params.json --infile /input/path/script.py
cq-cli --getparams /output/path/params.json --infile /input/path/script.py
```
10. Pass JSON parameter information from a file to be used in the script.
```
./cq-cli.py --codec stl --infile /input/path/script.py --outfile /output/path/output.stl --params /parameter/path/parameters.json
cq-cli --codec stl --infile /input/path/script.py --outfile /output/path/output.stl --params /parameter/path/parameters.json
```
11. Pass JSON parameter data as a string on the command line.
```
./cq-cli.py --codec stl --infile /input/path/script.py --params "{\"width\":10}"
cq-cli --codec stl --infile /input/path/script.py --params "{\"width\":10}"
```
12. String parameters can be defined using single quotes (`'`) or escaped double quotes (`\"`).
```
cq-cli --codec stl --outfile test.stl --infile /input/path/script.py --outputopts "width:2;tag_name:'test';centered:True"
```
```
cq-cli --codec stl --outfile test.stl --infile /input/path/script.py --outputopts "width:2;tag_name:\"test\";centered:True"
```

## Drawbacks

* The file (and directory) size for cq-cli is very large. cq-cli uses pyinstaller to package the binaries for each platform, and must embed all needed dependencies. The OCP and OCCT library dependencies add a minimum of ~270 MB of data on top of the included Python distribution. It is possible that the pyinstaller spec file could be optimized. If you are interested in helping with this, please let us know by opening an issue.
* Startup times for the single binary are relatively slow. If startup and execution time is important to you, consider using the pyinstaller_dir.spec spec file with pyinstaller: `pyinstaller pyinstaller_dir.spec`.

## Contributing

If you want to help improve and expand cq-cli, the following steps should get you up and running with a development setup. There is a [CadQuery Discord channel](https://discord.gg/qz3uAdF) and a [Google Group](https://groups.google.com/g/cadquery) that you can join to ask for help getting started.

### Anaconda Environment

A CadQuery Anaconda environment is required to run and build cq-cli via PyInstaller. For those unfamiliar (or uncomfortable) with Anaconda, it is probably best to start by installing Miniconda to a local directory and to avoid running `conda init`. After performing a local directory installation, an Anaconda environment can be activated via the [scripts,bin]/activate scripts. This will help avoid polluting and breaking the local Python installation.

Once the conda command is available, it is recommended that users build the environment from the latest master of the cadquery repo.
```
conda create -n cq-cli
conda activate cq-cli
conda install -c cadquery -c conda-forge cadquery=master
```
1. Create a Python virtual environment and activate it. Attept to avoid the bleeding-edge version of Python as there may be problems.
2. Clone this repository: `git clone https://github.com/CadQuery/cq-cli.git`
3. cd into the repository directory: `cd cq-cli`
4. Do a local editable installation via pip: `pip install -e .`

### Adding a Codec

Expand Down
2 changes: 2 additions & 0 deletions src/cq_cli/main.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -420,6 +420,8 @@ def main():
)
elif "." in op1:
op = float(opt_parts[1])
elif '"' in op1 or "'" in op1:
op = str(opt_parts[1])
else:
op = int(opt_parts[1])

Expand Down
Loading