New connectors proposal

[hrgdavor]

is open for discussion
is linked with issue: #856
is missing mat4.inverse
is open for proposal for alternate syntax for compact string format of connector options

• 'TBSW' -> {dir:'top', side:['bottom','south','west']}
• 'TBSW' -> {dir:'top', side:['bottom','front','left']}
• 'TT' -> {dir:'top', side:['top']}

first thoughts

What I think we need

• connector-decorators for each built-in geometry,
• connector-decorator adds getConnector method to geometry to calculate a connectors, later on,
• that pattern will allow modules with custom geometries to follow suit and provide own decorators
• changes to connector-decorator code-base would not affect geometries
• users could create own connector-decorators for basic geometries too if they have a need for additional connectors or different connector location syntax
• connector-decorator is called by providing the identical parameters one would provide for the geometry
• connector-decorator creates the same geometry (cuboid, sphere, cylinder, ...etc) but stores the provided parameters on the geometry
• getConnector method calculates a connectors based on some logic that makes sense for that geometry
• a cube connector-decorator could provide connectors on different faces and corners
• a pyramid connector-decorator would have different expectations
• a cylinder connector-decorator would have top or bottom, or on the side at some angle with some distance from bottom/top

A connector decorator is useful, because different geometries have different logical places where connectors could be and how to calculate their position.

After that we need a pattern to use and combine the connectors

• connect would use getConnector method from each geometry and apps parameters to it
• when combining connectors first one is fixed and other one is moved to it
• connect function can then do the transformations based on parameter for getConnector method of each geometry

initial concept

For this concept, a connector is just a transform matrix that

• moves the geometry from origin (xyz=0) to a location
• including rotation that defines the direction
• the initial direction of the object is Z axis

My preferred shortcut for connecting models that I already use in jscad scripts that I will use in these examples:

• T - top
• B - bottom
• N,S,E,W- compass
• I decided against: Left,Right,Top,Bottom,Front,Back because of first letter collision for Bottom and Back

if we have a cone that has the bottom of the cone at xyz=0 and top of the cone right above it

let cone = cylinderEllipticConnector({height:10, startRadius: [5,5], endRadius:[1]})
connect(cone,'TB') // if connect is used for only one geometry, then fixed point is xyz=0

when we move it to a connector on a cube it should

• have the bottom moved to that location
• be rotated so the direction of the cone is in the direction of the connector on the cube.
• if the cube is moved before connecting connect must combine transform of the cube with transform of the connector

example

Code using connectors that would be equal to creating a cuboid with size: [10,10,10]

let cube = cuboidConnector({size:[10,10,10]})
return cube;

Although it looks similar it gets better when you start moving things

// create cuboid, but use bottom-south-west corner  to place it at xyz origin.
// direction is to Top because first letter(T) is for direction, the rest are for location
let cube = cuboidConnector({size:[10,10,10]}, 'TBSW')// shortcut syntax that calls connect as well
return cube

The magic happens when you add cone to the East face of the cube

// create cuboid, but use bottom-south-west corner  to place it at xyz origin
// direction is to Top because first letter(T) is for direction, the rest are for location
let cube = cuboidConnector({size:[10,10,10]}, 'TBSW')// shortcut syntax that calls connect as well
let cone    = cylinderEllipticConnector({height:10, startRadius: [5,5], endRadius:[1]})
// connect cube by fixating at East side of cube, and moving bottom of the cone there
cone = connect(cube, 'EE',cone, 'TB') // original cone is not touched, a copy is created
// connect would do this by calling cube.getConnector('EE') and cone.getConnector('TB') and then do the move
return [cube, cone];

Add a sphere on top of the cone

let cube = cuboidConnector({size:[10,10,10]}, 'TBSW')
let cone    = cylinderEllipticConnector({height:10, startRadius: [5,5], endRadius:[1]})
cone = connect(cube,'EE', cone, 'TB') // original cone is not touched, a copy is created
return [cube, cone, connect(cone,'TT',sphere())];

As you can notice I did not use a sphereConnector but a regular sphere in the last example.
It should be possible to call connect without a connector-option for second geometry

• it that case it should just take current transform of the geometry
• it does not have to be something with getConnector method, but could also be a simple cylinder, coboid etc.

initial implementation

looks like it kinda works for the examples above, but it needs mat4.inverse that is not yet available.

function connect(geom1, param1, geom2, param2){
	const connector1 = geom1.getConnector(param1)
	// just one geometry, so we are actually connecting it to xyz=0 origin
	if(!geom2){
		let ret = {...geom1}
		ret.connectTransform = mat4.inverse(connector1)
		ret.transforms = mat4.multiply(mat4.create(),geom1.transforms,ret.connectTransform)
		return ret;
	}
	// the more complex case where we connect
	let ret = {...geom2}
	ret.transforms = mat4.clone(geom2.transforms);
	if(param2){
		const connector2 = mat4.inverse(geom2.getConnector(param2))
		// if the geometry was connected before, we must undo that connectmnet before applying the new one
		if(ret.connectTransform){
			ret.transforms = mat4.multiply(ret.transforms,ret.transforms,mat4.inverse(ret.connectTransform))
			ret.connectTransform = connector2
		}
		ret.transforms = mat4.multiply(ret.transforms,ret.transforms,connector2)
	}
	ret.transforms = mat4.multiply(ret.transforms, connector1, ret.transforms)
	ret.transforms = mat4.multiply(ret.transforms, geom1.transforms, ret.transforms)
	return ret
}

[z3dev]

@hrgdavor Small incremental changes like adding mat4.inverse is always fine.

Nice proposal with some nice ideas. I’ll think for awhile and post some additional thoughts later. :)

[hrgdavor]

@z3dev here is a script to play with: http://3d.hrg.hr/jscad/three/threejscad.html?uri=#model.connectors.js

the first option in the params is to rotate the cube so you can see how transformations to the cube will not break the connector.

Although align options on cone are easy to understand when not connected...
Cone is moved and rotated after connecting to the cube to match a connector on the cube.
Effectively, connecting operation transforms the origin of the cone.
After that TBNSW-orientation for cube and cone are not the same, they are no longer in same coordinate space.

the script code is:

funcs.main = function({//jscadparams
  // cube options
  rotateZ=0, // {type:'slider', max:360, live:1}
  // cube position connector
  cubeDir='T', // Direction {type:'choice', values:['T','B','N','S','E','W']}
  cubeTB='B', // Top/Bottom {type:'choice', values:['','T','B']}
  cubeNS='S', // North/South {type:'choice', values:['','N','S']}
  cubeEW='W', // East/West {type:'choice', values:['','E','W']}
  // cone position connector
  coneLocDir='T', // Direction {type:'choice', values:['T','B','N','S','E','W']}
  coneLocTB='B', // Top/Bottom {type:'choice', values:['','T','B']}
  // cone to cube connector
  cone2cube=true,// connect to cube
  cone2cubeDir='E', // Direction {type:'choice', values:['T','B','N','S','E','W']}
  cone2cubeTB='', // Top/Bottom {type:'choice', values:['','T','B']}
  cone2cubeNS='', // North/South {type:'choice', values:['','N','S']}
  cone2cubeEW='E', // East/West {type:'choice', values:['','E','W']}
}){

  let cubeLoc = cubeDir+cubeTB+cubeNS+cubeEW
  let coneLoc = coneLocDir+coneLocTB
  let cube2coneConnect = cone2cubeDir+cone2cubeTB+cone2cubeNS+cone2cubeEW
  
  let cube = cuboidConnector({size:[10,10,20]}, cubeLoc)
  cube.color = [1,0,0,0.5]// colorize will destory conenctor functions, so we hack the color into geom

  // rotate teh cube before connecting a cone to it to demonstrate connector respecting transforms
  cube = rotate([0,0,toRad(rotateZ)], cube)

  let cone = cylinderEllipticConnector({height:12, startRadius: [5,5], endRadius:[1,1]},coneLoc)
  cone.color = [0,1,0,0.5]// colorize will destory conenctor functions, so we hack the color into geom

  if(cone2cube) cone = connect(cube,cube2coneConnect, cone,coneLoc )
  return [cube, cone, connect(cone,'TT',sphere())]; 
}

// rotate that does not destroy geom other options like connectors
rotate = function(angles,geom){
  const yaw   = angles[2]
  const pitch = angles[1]
  const roll  = angles[0]

  const matrix = mat4.fromTaitBryanRotation(mat4.create(), yaw, pitch, roll)

  return {...geom, transforms:mat4.multiply(mat4.create(),matrix, geom.transforms)}
}

you will notice some options may give oposite result than you would expect, but that is something that can be discussed, and some kind of consistent principle could be applied