V2 checklist

[kaosat-dev]

Before being able to merge V2 into master (when we get there) we need to validate the following checklist

V2 is a major overhaul of both the geometric core, common code & ui

• side effects (http, file system, dom) are now clear , seperate entities
• require() support for client side is fully working & tested
• combines / upgrades the web ui with the desktop advances (amongst other things)
  • updated 3D viewer
  • keyboard shortcuts
  • modules support
  • allow multiple instances of jscad per page easilly
  • very simple api for embeding a jscad instance
  • completely restructured internals
  • maximized reuse of code between uis
  • lots more !!

geometric kernel

• use of csg V2 with all that it implies (and eliminate old CSG)

io

• updated ALL IO to use csg V2 after the above is done (lots of work)
  • AMF : deserializer DONE, serializer DONE
  • DXF : deserializer DONE, serializer DONE
  • GCODE : deserializer DROP
  • JSON : deserializer DONE, serializer DONE
  • OBJ : deserializer DONE
  • SCAD : deserializer DO NOT FIX, waiting for someone to own this
  • STL : deserializer DONE, serializer DONE
  • SVG : deserializer DONE, serializer DONE
  • X3D : serializer DONE

common / core

• create arrayUtils and refactor
• vtree needs to be updated for V2

web and desktop

inputs

• drag and drop of files
• drag and drop of folders
• loading of remote files
• conversion of files
• require support , injection of explicit api
• require support , geometry caching
• require support relative paths
• require support node_modules (DONE via V2 : enhance webrequire to support node_modules #587)
• require support single file
• file watcher/autoreload for single file
• file watcher/autoreload for folders
• examples
• virtual fs module injection ie allow const fs = require('fs') in the browser

outputs

• save/export of files using v2 api

error handling

• fix unhandled and explicit error handling
• make error handling from different sources coherent (web worker, http requests etc)
• fix handling of http request errors 4xx
• fix handling of http request errors (all)

3D viewer

• 3d viewer basics
• zoom to fit settable
• no resetting of camera to previous state
• all 3D viewer instances should behave independently
• improve rendering of 2d lines (no lighting)

code editor

• code editor basics

ui

• shortcuts : settable
• theming

general

• migrate examples to new API
• translations
• multiple instances per page
• coherent input/outputs handling
• correct timeout and geometry generation cancellation
• correct error displaying

tests

• side effects

docs

• document generation from jsdoc strings in code
• document modeling API
• document examples
• document how to convert V1 to V2

final checklist if all the above is done

• works in latest Chrome
• works in latest Firefox
• works in latest Safari
• works in latest Edge
• works on mobile; iOS and Android devices
• works on Windows 10
• works on MacOS
• works on Linux
• proxy

closes #119
closes #137
closes #167
closes #235
closes #245
closes #321
closes #327
closes #336
closes #343
closes #344
closes #364
closes #378

[kaosat-dev]

while integrating the new CSG V2 , a few questions/ issues also popped up:

Modeling

• what namespacing are we going to use? 'modeling'
  ie const jscad = require('@jscad/modeling') or something else ?
• Should ‘modeling/color’ be ‘colors’? (decision, 'color)
• Should ‘modeling/geometry’ be ‘geometries’ (decision, geometry)
• should 'modeling/math' be 'maths'? (decision, math)

Geometry

• geom3: add invert function to invert the polygons (Done via V2 : add invert() to geom3 #604)

Primitives

• resolution/segments too low (DONE as part of V2 : enhance primitives #574)
  • 2D shapes; 32 segments
  • 3D shapes; 32 segments
• cylinder : no radius option, only start/end radius (IN PROGRESS as part of V2 : enhance primitives #574)
• center parameter should be removed (done as part of V2: Remove 'center' on primitives #489)
• polyhedron: add colors parameter for deserializers (DONE as part of V2 : enhanced polyhedron to accept an array of colors #544)

Operations

• translate (DONE as part of V2 : fix transforms #521 )
  • throws message for missing axis (fill in axis if missing)
  • 'offsets' options is not clear, nor whether it is translate or not (wolfram term)
  • alternatives: 'direction'? 'vector'? 'offset'?
  • forces 3 axis, not logical for 2d translate (fill in last axis if missing)
• extrudeWalls: what is it ? what does it do ? (INTERNAL ONLY, NOT EXPORTED)

Color

• there is no more color('black', xxx): we should make it clear that there is another, separate function to generate colors from names (DONE as part of V2 : cleanup color api #542)
• change functions to hslToRgb(...values), hsvToRgb(...values) (DONE as part of V2 : cleanup color api #542)
• change functions to rgbToHex(...values), rgbToHsl(...values), rgbToHsv(...values) (DONE as part of V2 : cleanup color api #542)
• color() docstrings mention rgba , but both examples only show rgb (DONE as part of V2 : cleanup color api #542)
• const color = require('@jscad/modeling').color.color feels very odd, api wise
  • rename color => colors, DONE as part of Color.color -> colors.colorize #591

Measurements:

• measureBounds : bad wording, as the measurement is an axis aligned bounding box
  • (z3dev) measureBoundingBox seems appropriate (DONE as part of V2 : move measurements #628)
• operations/measurements should perhaps be moved one level up (DONE as part of V2 : move measurements #628)
  • other operations return a new transformed shape, but these only give information/measurement about the shapes
  • (z3dev) agree as there will be more measurements

Parsers/ IO:

• correct deserializers (DONE as part of V2 : Fix Deserializers #527)
  • should use {output: 'geometry'} only (not csg or cag or etc)
  • should have standard signature; deserialize(options, rawData)
  • options should include filename; {filename: 'myfile'}
• stl-deserializer: use polyhedron() from 'modeling' (part of V2 STL Deserializer #466)
• packages/core/io/formats.js needs to be cleaned up (part of V2 : Fixes to WEB #505)
• move all of core/io to packages/io (part of V2: move convertToBlob from core/io to io-utils for coherence & practicality #509)
• convert json serializer to V2 (DONE as part of V2 : Upgrade JSON Serializer #545)
• convert json deserializer to V2 (DONE as part of V2 : Upgrade JSON Deserializer #546)

Tests

• fix cli tests (DONE as part of V2 : simple test suite for cli #541)
  • disabled because of lack of V2 examples, etc
  • create simple test suite to test conversions, independent of examples
• create tests for array-utils (DONE as part of V2 : test array utils #539)
• create tests for io/io-utils (DONE)

General

• create arrayUtils and refactor (part of V2: move convertToBlob from core/io to io-utils for coherence & practicality #509)
• drop unused, untested, unreferenced files
  • core (DONE)
  • io (DONE)
  • modeling (DONE)
  • utils (DONE)
  • vtree
  • web (DONE)
• cleanup lint warnings (DONE as part of V2: Lint #571)
• while working on examples it REALLY became even clearer that we need a way to have chaining/piping of functions, as it can get cumbersome with multiple nested functions (see previous discussions on this, V2 : ensure curryability of api csg.js#114)
• create simple release script : auto gen & co for docs (IN PROGRESS)

Docs

• verify and update all README files for V2 (DONE as part of V2 : general cleanup of readme files #549)
• add notes regarding gl-matrix & co 'the maths library and modularity is based on the gl-matrix and its split up versions' (DONE as part of V2 : general cleanup of readme files #549)

[z3dev]

Here’s another list of issues / questions.

1. Should ‘modeling/color’ be ‘colors’
2. Should ‘modeling/geometry’ be ‘geometries’

[kaosat-dev]

const {sin, cos, tan, sqrt, lookup} = require('${apiMainPath}').maths => I need to double check but lookup is missing and might be needed ?

[z3dev]

const {sin, cos, tan, sqrt, lookup} = require('${apiMainPath}').maths => I need to double check but lookup is missing and might be needed ?

Why? For SCAD compatibility? We decided to break from SCAD and CSG APIs.

[kaosat-dev]

I still do not understand why you mention SCAD regularly ? I only view things as 'what parts of any previous API was useful', not where/how/what it came from.

I meant the lookup function specifically : it is used in at least a few examples, and might (emphasis on might) still be useful for some people

[kaosat-dev]

math => maths (plural is the standard as far as I know)

[kaosat-dev]

1. Should ‘modeling/color’ be ‘colors’
2. Should ‘modeling/geometry’ be ‘geometries’

I think in both cases I think the current naming is fine and the best option to be honest :)

[z3dev]

1. Should ‘modeling/color’ be ‘colors’
2. Should ‘modeling/geometry’ be ‘geometries’

I think in both cases I think the current naming is fine and the best option to be honest :)

I’m fine. But let’s be consistent and keep ‘math’. I think this is the best option. :)

[z3dev]

browser list for desktops / laptops... shouldn't IE be included? Or Microsoft Edge?

Currently, it seems to be trending from IE to EDGE. Maybe we should just verify edge, which is far more compliant with standards.

[z3dev]

We need to pull items from these issues

#323 (closed)
jscad/io#64 (closed)
jscad/csg.js#193 (closed)
jscad/csg.js#187 (closed)
jscad/csg.js#114
jscad/csg.js#96 (closed)

And close these if possible.

[kaosat-dev]

I can move some of those to here , makes sense
Big question: should we close some issues despite not having a "final V2 release" yet ? (what we seem to be heading to is more of a 'rolling release' which is better imho ?)

[z3dev]

Big question: should we close some issues despite not having a "final V2 release" yet ?

I think this makes sense, especially if there’s a specific test for the issue. This will make issue management easier, as well as the releases.

Just one thing... let's mark each issue being closed with "V2" before closing.

[kaosat-dev]

@z3dev please, do not delete my comments, it makes the conversation harder to follow, as I do not know what, or why was deleted, thanks :)

[kaosat-dev]

@z3dev
about pipe() , I found that as soon as you have more than two operands being chained/wrapping, it makes code considerably more readable:

const lotsOfOps = pipe(
  union(transformedRectangle, movedEllipse),
  translate([1, 0, 0]),
  centerAt([10, -25, 0]),
  translate([2, 0, 0]),
  scale([1, 2, 1]),
  color([1, 0, 0, 0.5])
)

// without pipe
const lotsOfOpsOld = color([1, 0, 0, 0.5],
  scale([1, 2, 1],
    translate([2, 0, 0],
      centerAt([10, -25, 0],
        translate([1, 0, 0],
          union(transformedRectangle, movedEllipse)
        ))))
)

[z3dev]

@garrlker How about taking something from the second list? There are some small changes to API functions, additional tests to create, etc.

[garrlker]

@z3dev Sure,

I'll take a couple from the 'Primitives' list.

Like circle : no diameter option and cylinder : no radius or diameter option, only start/end radius.

I'll check if an issue is already created for either, if not I'll make my own.

[z3dev]

I'll take a couple from the 'Primitives' list.

Like circle : no diameter option and cylinder : no radius or diameter option, only start/end radius.

Cool. FYI, I’m working on the IO modules currently. We should not overlap. :)

[z3dev]

FYI, I'm creating a couple of WIKI pages for Early Adopters of V2. A lot has changed some a little documentation can go a long way.

https://openjscad.org/dokuwiki/doku.php?id=early_v2

[udif]

Is https://jscad.xyz/ reflecting current V2 code?
Is it possible to add a CI job to build v2 on github pages?
I use v1 on the web almost exclusively because it lets me share links with my designs for other people to look at without forcing them to install anything.

[z3dev]

Is https://jscad.xyz/ reflecting current V2 code?

Not yet. Early adopters need to clone this repository.

Is it possible to add a CI job to build v2 on github pages?

One of the remaining tasks is to create an automated release and distribution script.

[z3dev]

@garrlker How about taking something from the second list? There are some small changes to API functions, additional tests to create, etc.

@garrlker any progress on these changes? any issues?

[z3dev]

@kaosat-dev we have discussed this before but this is really weird...

const color = require('@jscad/modeling').color.color feels very odd

I totally agree, but what’s the correct namespace? Do we only expect colors? What about shades? Or textures? Or materials?

[kaosat-dev]

gaah, I thought I had replied !
@z3dev the only thing I see is changing the namespace to colors (plural), then It is slightly less odd
I also like the plural because there are multiple color related functions ? (just like I favor maths as plural :D )

[z3dev]

Closing as V2 JSCAD has been released.

Any outstanding tasks have been converted to issues.