Merge pull request #110 from jsconan/release-1.6.0

Release 1.6.0

HISTORY.md

@@ -1,5 +1,25 @@
 # camelSCAD history
 
+## [Version 1.6.0](https://github.com/jsconan/camelSCAD/releases/tag/v1.6.0)
+
+Add core functions:
+
+-   `interpolationThreshold()`: Computes the threshold for a particular interpolation step considering the expected number of steps, and with respect to start and end thresholds.
+
+Add operators:
+
+-   `presentAnimate()`: Presents the child modules only between the start and end thresholds, with respect to the `$t` variable.
+
+Update script utils:
+
+-   Add color for the warning messages.
+-   Add the function `buildpath` to build a destination path from a list of parts.
+-   Add the function `scadversion` to get the version of the installed OpenSCAD.
+-   Add the function `sclic3rversion` to get the version of the installed Slic3r.
+-   Add the function `scadpreview` to render a capture of a SCAD model.
+-   Add the function `scadecho` to capture the echos printed by a model.
+-   Accept other parameters than variable definitions when calling OpenSCAD.
+
 ## [Version 1.5.0](https://github.com/jsconan/camelSCAD/releases/tag/v1.5.0)
 
 Add operators to ease scenes animation:

core/maths.scad

@@ -528,3 +528,24 @@ function interpolateStep(step, low, high, start, end, domain, values, range) =
        :simpleInterpolationRange(low=low, high=high, start=start, end=end, domain=domain)
     )
 ;
+
+/**
+ * Computes the threshold for a particular interpolation step considering the expected number of steps,
+ * and with respect to start and end thresholds.
+ * @param Number step - The current step.
+ * @param Number steps - The total number of expected steps.
+ * @param Number [start] - The start threshold under what the low value will persist and above what it will be interpolated.
+ * @param Number [end] - The end threshold above what the high value will persist and under what it will be interpolated.
+ * @param Number [domain] - The percentage domain applied to compute the percentage ratio for the thresholds (default: 100).
+ * @returns Number
+ */
+function interpolationThreshold(step, steps, start, end, domain) =
+    let(
+        step = float(step),
+        steps = divisor(steps),
+        start = abs(percentage(numberOr(start, 0), domain=domain)),
+        end = abs(percentage(numberOr(end, 1), domain=domain)),
+        range = max(start, end) - min(start, end)
+    )
+    start + step * range / steps
+;

core/version.scad

@@ -36,7 +36,7 @@
  * The version of the library.
  * @type Vector
  */
-CAMEL_SCAD_VERSION = [1, 5, 0];
+CAMEL_SCAD_VERSION = [1, 6, 0];
 
 /**
  * The minimal version of OpenSCAD required by the library.

operator/animate/mirror.scad

@@ -42,7 +42,6 @@
  * @param Number [domain] - The percentage domain used to compute the thresholds (default: 100).
  * @param Vector [values] - A list of axis composing the range to interpolate.
  * @param Vector [range] - A pre-built interpolation range. If missing, it will be built from the parameters `from`, `to`, `start`, `end`, `domain`.
- * @returns Number
  */
 module mirrorAnimate(from, to, start, end, domain, values, range) {
     mirror(interpolateStep3D(step=$t, low=from, high=to, start=start, end=end, domain=domain, values=values, range=range)) {

operator/animate/present.scad

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * MIT License
+ *
+ * Copyright (c) 2022 Jean-Sebastien CONAN
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * Part of the camelSCAD library.
+ *
+ * Operators that animate child modules with respect to particular rules.
+ *
+ * @package operator/animate
+ * @author jsconan
+ */
+
+/**
+ * Presents the child modules only between the start and end thresholds, with respect to the `$t` variable.
+ *
+ * @param Number [start] - The start threshold under what the child modules will be hidden and above what they will be presented.
+ * @param Number [end] - The end threshold above what the child modules will be hidden and under what they will be presented.
+ * @param Number [domain] - The percentage domain used to compute the thresholds (default: 100).
+ */
+module presentAnimate(start, end, domain) {
+    start = abs(percentage(numberOr(start, 0), domain=domain));
+    end = abs(percentage(numberOr(end, 1), domain=domain));
+    if( $t >= min(start, end) && $t <= max(start, end) ) {
+        children();
+    }
+}

operator/animate/resize.scad

@@ -43,7 +43,6 @@
  * @param Vector [values] - A list of sizes composing the range to interpolate.
  * @param Vector [range] - A pre-built interpolation range. If missing, it will be built from the parameters `from`, `to`, `start`, `end`, `domain`.
  * @param Boolean [auto] - When set to `true`, it auto-scales any 0-dimensions to match. It can also be used to auto-scale a single dimension and leave the other as-is.
- * @returns Number
  */
 module resizeAnimate(from, to, start, end, domain, auto, values, range) {
     resize(interpolateStep3D(step=$t, low=from, high=to, start=start, end=end, domain=domain, values=values, range=range), auto=auto) {

operator/animate/rotate.scad

@@ -42,7 +42,6 @@
  * @param Number [domain] - The percentage domain used to compute the thresholds (default: 100).
  * @param Vector [values] - A list of angles composing the range to interpolate.
  * @param Vector [range] - A pre-built interpolation range. If missing, it will be built from the parameters `from`, `to`, `start`, `end`, `domain`.
- * @returns Number
  */
 module rotateAnimate(from, to, start, end, domain, values, range) {
     rotate(interpolateStep3D(step=$t, low=from, high=to, start=start, end=end, domain=domain, values=values, range=range)) {

operator/animate/scale.scad

@@ -42,7 +42,6 @@
  * @param Number [domain] - The percentage domain used to compute the thresholds (default: 100).
  * @param Vector [values] - A list of scale ratios composing the range to interpolate.
  * @param Vector [range] - A pre-built interpolation range. If missing, it will be built from the parameters `from`, `to`, `start`, `end`, `domain`.
- * @returns Number
  */
 module scaleAnimate(from, to, start, end, domain, values, range) {
     scale(interpolateStep3D(step=$t, low=from, high=to, start=start, end=end, domain=domain, values=values, range=range)) {

operator/animate/translate.scad

@@ -42,7 +42,6 @@
  * @param Number [domain] - The percentage domain used to compute the thresholds (default: 100).
  * @param Vector [values] - A list of coordinates composing the range to interpolate.
  * @param Vector [range] - A pre-built interpolation range. If missing, it will be built from the parameters `from`, `to`, `start`, `end`, `domain`.
- * @returns Number
  */
 module translateAnimate(from, to, start, end, domain, values, range) {
     translate(interpolateStep3D(step=$t, low=from, high=to, start=start, end=end, domain=domain, values=values, range=range)) {

operators.scad

@@ -36,6 +36,7 @@ include <core.scad>
 
 /* OPERATORS */
 include <operator/animate/mirror.scad>
+include <operator/animate/present.scad>
 include <operator/animate/resize.scad>
 include <operator/animate/rotate.scad>
 include <operator/animate/scale.scad>

scripts/render.sh

@@ -112,7 +112,7 @@ if [ ! -d "${srcpath}" ]; then
     printerror "The input path ${srcpath} does not exist!"
 fi
 if [ ! -d "${dstpath}" ]; then
-    printmessage ${C_ERR}"Warning! The output path ${dstpath} does not exist!"
+    printmessage ${C_WRN}"Warning! The output path ${dstpath} does not exist!"
 fi
 
 # check OpenSCAD

scripts/slice.sh

@@ -126,7 +126,7 @@ if [ ! -d "${srcpath}" ]; then
     printerror "The input path ${srcpath} does not exist!"
 fi
 if [ ! -d "${dstpath}" ]; then
-    printmessage ${C_ERR}"Warning! The output path ${dstpath} does not exist!"
+    printmessage ${C_WRN}"Warning! The output path ${dstpath} does not exist!"
 fi
 
 # check Slic3r
@@ -137,7 +137,7 @@ slic3rformat "${format}"
 
 # defines the config path
 if [ "${configpath}" != "" ] && [ ! -f "${configpath}" ]; then
-    printmessage "${C_ERR}Warning! The config for Slic3r does not exist."
+    printmessage "${C_WRN}Warning! The config for Slic3r does not exist."
 fi
 slic3rconfig "${configpath}"
 

scripts/test.sh

@@ -101,7 +101,7 @@ if [ ! -d "${srcpath}" ]; then
     printerror "The input path ${srcpath} does not exist!"
 fi
 if [ ! -d "${dstpath}" ]; then
-    printmessage ${C_ERR}"Warning! The output path ${dstpath} does not exist!"
+    printmessage ${C_WRN}"Warning! The output path ${dstpath} does not exist!"
 fi
 
 # check OpenSCAD

scripts/utils/display.sh

@@ -34,6 +34,7 @@
 
 # List of color codes
 export C_ERR="\033[31m"
+export C_WRN="\033[35m"
 export C_SEL="\033[32m"
 export C_SPE="\033[33m"
 export C_CTX="\033[36m"

scripts/utils/files.sh

@@ -2,7 +2,7 @@
 #
 # GPLv3 License
 #
-# Copyright (c) 2019 Jean-Sebastien CONAN
+# Copyright (c) 2019-2022 Jean-Sebastien CONAN
 #
 # This file is part of jsconan/things.
 #
@@ -128,3 +128,33 @@ recursepath() {
         fi
     done
 }
+
+# Builds a file path.
+#
+# @example
+# buildpath "bar.scad" "foo/bar"                   # will build the path foo/bar/bar.scad
+# buildpath "bar.scad" "foo/bar" "" "foo"          # will build the path foo/bar/foo-bar.scad
+# buildpath "bar.scad" "foo/bar" "" "" "baz"       # will build the path foo/bar/bar-baz.scad
+# buildpath "bar.scad" "foo/bar" "" "foo" "baz"    # will build the path foo/bar/foo-bar-baz.scad
+# buildpath "bar.scad" "foo/bar" "stl"             # will build the path foo/bar/bar.stl
+# buildpath "bar.scad" "foo/bar" "stl" "foo"       # will build the path foo/bar/foo-bar.stl
+# buildpath "bar.scad" "foo/bar" "stl" "" "baz"    # will build the path foo/bar/bar-baz.stl
+# buildpath "bar.scad" "foo/bar" "stl" "foo" "baz" # will build the path foo/bar/foo-bar-baz.stl
+#
+# @param filepath - The path to the original file.
+# @param destpath - The path to the file.
+# @param extension - A file extension to set to the file name.
+# @param prefix - A prefix to add to the file name.
+# @param suffix - A suffix to add to the file name.
+buildpath() {
+    local filepath="$1";
+    local destpath="$2";
+    local extension=$(prefixif "." "$3");
+    local prefix=$(suffixif "$4" "-");
+    local suffix=$(prefixif "-" "$5");
+    local name=$(basename "${filepath%.*}")
+    if [ "${extension}" == "" ]; then
+        extension=$(prefixif "." "${filepath##*.}");
+    fi
+    echo "${destpath}/${prefix}${name}${suffix}${extension}"
+}

scripts/utils/scad.sh

@@ -41,6 +41,9 @@ export scadver="2019.05"
 # Defines the file extension for OpenSCAD files
 export scadext="scad"
 
+# Defines the file extension for echo prints
+export echoext="echo"
+
 # Defines the file format for the rendering output
 export scadout="stl"
 
@@ -91,6 +94,28 @@ scadmoduleuri() {
     fi
 }
 
+# Gets the version of the installed OpenSCAD.
+# Exits with error code E_OPENSCAD if not installed.
+#
+# @example
+# scadversion       # will display "xxxx.xx"
+#
+# scadversion "foo" # will display "xxxx.xx", or return E_OPENSCAD if not installed
+#
+# @param [openscad] - The path to the OpenSCAD command (default "openscad").
+scadversion() {
+    local version
+    local cmd="${scadcmd}"
+    if [ "$1" != "" ]; then
+        cmd="$1"
+    fi
+    version=$(${cmd} -v 2>&1)
+    if [ "$?" != "0" ]; then
+        return ${E_OPENSCAD}
+    fi
+    echo "${version//[^0-9.]/}"
+}
+
 # Checks if OpenSCAD is installed.
 # Exits with error code E_OPENSCAD if not installed.
 #
@@ -105,19 +130,19 @@ scadmoduleuri() {
 #
 # @param [openscad] - The path to the OpenSCAD command (default "openscad").
 scadcheck() {
-    local info=
+    local info
+    local version
     if [ "$1" != "" ]; then
         scadcmd="$1"
         info=" [from ${C_SEL}${scadcmd}${C_RST}]"
     fi
     printmessage "Detecting ${C_SPE}OpenSCAD${C_RST}${info}..."
-    local scad=$(${scadcmd} -v 2>&1)
+    version=$(scadversion)
     if [ "$?" != "0" ]; then
         printerror "It seems OpenSCAD has not been installed on your system.\nOr perhaps is it just not reachable...\nHave you placed it in your environment PATH variable?" ${E_OPENSCAD}
     else
         printmessage "${C_SPE}OpenSCAD${C_RST} has been detected."
     fi
-    local version="${scad//[^0-9.]/}"
     if [[ "${version}" < "${scadver}" ]]; then
         printerror "The installed version of OpenSCAD does not meet the requirement.\n\tInstalled: ${version}\n\tRequired: ${scadver}" ${E_OPENSCAD}
     fi
@@ -141,11 +166,13 @@ scadcall() {
     local params=()
     for var in "$@"; do
         if [ "${var}" != "" ]; then
-            params+=("-D")
+            if [[ "${var}" == *=* ]]; then
+                params+=("-D")
+            fi
             params+=("${var}")
         fi
     done
-    ${scadcmd} --render -o "${outputpath}" "${sourcepath}" "${params[@]}"
+    ${scadcmd} -o "${outputpath}" "${sourcepath}" "${params[@]}"
 }
 
 # Set the format of the ouput files.
@@ -188,20 +215,60 @@ scadprocesses() {
 # scadrender "bar.scad" "foo/bar" "foo" "baz" # will render a STL file at foo/bar/foo-bar-baz.stl
 #
 # @param filepath - The path of the SCAD file to render.
-# @param destpath - The path to the output file.
+# @param destpath - The path to the output folder.
 # @param prefix - A prefix to add to the output file.
 # @param suffix - A suffix to add to the output file.
 # @param ... - A list of pre-defined variables.
 scadrender() {
-    local filepath="$1"; shift
-    local destpath="$1"; shift
-    local prefix=$(suffixif "$1" "-"); shift
-    local suffix=$(prefixif "-" "$1"); shift
+    local filepath="$1";
+    local filename=$(basename "${filepath}")
+    local outputpath=$(buildpath "$1" "$2" "${scadout}" "$3" "$4")
+    shift $(($# > 4 ? 4 : $#))
+    printmessage "${C_RST}Rendering of ${C_SEL}${filename}${C_RST} to ${C_SEL}${outputpath}"
+    scadcall "${filepath}" "${outputpath}" --render "renderMode=\"prod\"" "$@"
+}
+
+# Previews a module.
+#
+# @example
+# scadpreview "bar.scad" "foo/bar" "png"             # will preview a STL file at foo/bar/bar.png
+# scadpreview "bar.scad" "foo/bar" "png" "foo"       # will preview a STL file at foo/bar/foo-bar.png
+# scadpreview "bar.scad" "foo/bar" "png" "foo" "baz" # will preview a STL file at foo/bar/foo-bar-baz.png
+#
+# @param filepath - The path of the SCAD file to preview.
+# @param destpath - The path to the output folder.
+# @param extension - The file extension for the ouput file.
+# @param prefix - A prefix to add to the output file.
+# @param suffix - A suffix to add to the output file.
+# @param ... - A list of pre-defined variables.
+scadpreview() {
+    local filepath="$1";
+    local filename=$(basename "${filepath}")
+    local outputpath=$(buildpath "$1" "$2" "$3" "$4" "$5")
+    shift $(($# > 5 ? 5 : $#))
+    printmessage "${C_RST}Rendering of ${C_SEL}${filename}${C_RST} to ${C_SEL}${outputpath}"
+    scadcall "${filepath}" "${outputpath}" --preview "renderMode=\"prod\"" "$@"
+}
+
+# Prints the echos from a module.
+#
+# @example
+# scadecho "bar.scad" "foo/bar"             # will preview a STL file at foo/bar/bar.echo
+# scadecho "bar.scad" "foo/bar" "foo"       # will preview a STL file at foo/bar/foo-bar.echo
+# scadecho "bar.scad" "foo/bar" "foo" "baz" # will preview a STL file at foo/bar/foo-bar-baz.echo
+#
+# @param filepath - The path of the SCAD file from which get the echos.
+# @param destpath - The path to the output folder.
+# @param prefix - A prefix to add to the output file.
+# @param suffix - A suffix to add to the output file.
+# @param ... - A list of pre-defined variables.
+scadecho() {
+    local filepath="$1";
     local filename=$(basename "${filepath}")
-    local name=$(scadmodulename "${filepath}")
-    local outputpath="${destpath}/${prefix}${name}${suffix}.${scadout}"
+    local outputpath=$(buildpath "$1" "$2" "${echoext}" "$3" "$4")
+    shift $(($# > 4 ? 4 : $#))
     printmessage "${C_RST}Rendering of ${C_SEL}${filename}${C_RST} to ${C_SEL}${outputpath}"
-    scadcall "${filepath}" "${outputpath}" "renderMode=\"prod\"" "$@"
+    scadcall "${filepath}" "${outputpath}" --preview "renderMode=\"prod\"" "$@"
 }
 
 # Renders the files from a path. Several processes will be spawned at a time to parallelize the rendering and speeds it up.