PR #2475: Expression syntax extension

[realthunder]

PR link here

Changes include:

Add internal function list/tuple(). Spreadsheet range expression can be expanded to list or tuple, e.g.

Code: Select all

list(A1:A10)

Use Python number protocol in OperatorExpression, so you can doing something like matrix * vector, rotation * vector, or formatted string like

Code: Select all

<<This is formatted string %s and %s>> % tuple(A1; A2)

Extended indexing support

Code: Select all

A1[B2+1][C3][D4:-1]

New constant, None, True, true, False, false.

Sub-object referencing scheme. This can be useful if for example, the 'Group' below is a link to an external object, so Box is not inside the same document.

Code: Select all

Group.<<Box.>>.Placement
# or, with sub-object label referencing
Group.<<$Cube.>>.Placement

BTW, although not related to this PR, the tree view object search function now supports expression, including auto complete. So you can use full qualified object referencing for wider range of search. Type '<<' to get autocomplete with label references. The sub-object referencing mentioned above is also supported, although autocomplete does not quite support that yet.

search.gif (329.19 KiB) Viewed 9024 times

EDIT: To serve as a temporary document of the extended expression engine. I'll list some additional features here.

New local property referencing syntax. Say you want to reference an object's placement base in an expression for the same object. The old syntax Placement.Base may have ambiguity problem in case there is an object also named as 'Placement'. You can use the new local property referencing syntax .Placement.Base to avoid ambiguity.

New built-in functions,

Code: Select all

create(type, ...)
# Creates a python object of 'type'
# 'type' shall be a string. Currently supported types are, placement, rotation, vector, and matrix.
# Additional argument are passed to those python object's constructor.
# E.g. create(<<vector>>, 1, 0, 0)

mscale(matrix, vector)
mscale(matrix, number, number, number)
# Scale the matrix with the given vector

minvert(matrix|placement|rotation)
# Invert the given matrix, placement or rotation

To bind an expression to any property, right click in the property view and check 'Show all'. This reveals all hidden properties, and also enables the 'Expression...' menu action. Now right click any property you want to bind, and selection 'Expression...' to edit.

There is a new way to batch edit expressions using treeview context menu item 'Expression actions...'. There are sub menu actions,
* Copy selected: copy only expressions of the selected objects
* Copy active document: copy expressions of all objects in the active document
* Copy all document: copy expressions of all objects in all open documents.
* Paste: paste what every expressions in the clipboard

The copied expression is in plain text format, and you can edit it using any text editor. Each expression is preceded by two special lines with marker ##@@. The first line contains

Code: Select all

<binding_property_path> <document_name>#<object_internal_name>.<expression_hosting_property> (<object_label>)

The second line is for comments. But for spreadsheet cells, this comment line has special purpose for holding cell styles, including alias. You can batch edit any of these, and paste it back. An example of the copied expressions is shown below.

Code: Select all

##@@ .Placement.Base.x Unnamed#Box.ExpressionEngine (Cube)
##@@
Width

##@@ A1 Unnamed#Spreadsheet.cells (Spreadsheet)
##@@
Box.Placement.Base

##@@ A2 Unnamed#Spreadsheet.cells (Spreadsheet)
##@@<Cell alias="box_base" />
create(<<vector>>; Box.Width; Box.Height; Box.Length)

[kunda]

Nice!!!
Edit: need to take a look in the Tracker at the Expressions/Spreadsheet tickets to see what this PR addresses

[Zolko]

Use Python number protocol in OperatorExpression, so you can doing something like matrix * vector, rotation * vector

Sub-object referencing scheme. This can be useful if for example, the 'Group' below is a link to an external object, so Box is not inside the same document.

Code: Select all

Group.<<Box.>>.Placement
# or, with sub-object label referencing
Group.<<$Cube.>>.Placement

Thank-you, that's great achievement.

EDIT: does this allow to call methods on objects ? Like :

Code: Select all

Group.<<Box.>>.Placement.multiply( Group.<<$Cube.>>.Placement.inverse() )

For info, these extensions to the ExpressionEngine are used by the Assembly 4 workbench, with the App::Link framework, so it would be extremely useful to have this PR included alongside the App::Link merge for FreeCAD v0.19. See also thread in forum

[realthunder]

EDIT: does this allow to call methods on objects ? Like :

No, you cannot call methods. The equivalent expression will be

Code: Select all

Group.<<Box.>>.Placement.Matrix * Group.<<$Cube.>>.Placement.Matrix ^ -1

The result is a matrix, but you can bind it directly to a Placement property.

[Zolko]

EDIT: does this allow to call methods on objects ? Like :

Code: Select all

Group.<<Box.>>.Placement.multiply( Group.<<$Cube.>>.Placement.inverse() )

No, you cannot call methods.

ah ... that's a pity. In your -asm3 branch it is possible. Is it very difficult to implement it here also ? Is there a technical hurdle ? May-be there would be other use-cases than Asm4

The equivalent expression will be

Code: Select all

Group.<<Box.>>.Placement.Matrix * Group.<<$Cube.>>.Placement.Matrix ^ -1

I'm not sure it's equivalent. You can combine rotations like that, but a Placement has also a translation.

[realthunder]

ah ... that's a pity. In your -asm3 branch it is possible. Is it very difficult to implement it here also ? Is there a technical hurdle ? May-be there would be other use-cases than Asm4

The technical difficulty is to make it secure. Calling into object opens up a lot more attack surface. I'll work on that eventually, but probably not in the near future. You can propose required function. It is more secure to whitelist than blacklist, relatively speaking.

I'm not sure it's equivalent. You can combine rotations like that, but a Placement has also a translation.

Yes, this is equivalent. It's a 4x4 matrix that captures the whole placement. It can even carry scale/mirror transformation that are not representable for placement.

[Zolko]

The technical difficulty is to make it secure. Calling into object opens up a lot more attack surface. [...] It is more secure to whitelist than blacklist, relatively speaking.

ah yes, I understand, of course. Soooo ... what about white listing Placement.multiply() and Placement.inverse() ?

EDIT: or Placement.everything() for that matter, there are only a handful methods for Placement.

I'm not sure it's equivalent. You can combine rotations like that, but a Placement has also a translation.

Yes, this is equivalent. It's a 4x4 matrix that captures the whole placement.

I have doubts: in Base/Placement.cpp

Code: Select all

void Placement::invert()
{
    this->_rot = this->_rot.inverse();
    this->_rot.multVec(this->_pos, this->_pos);
    this->_pos = -this->_pos;
}

meaning that a rotation's inverse() is effectively it's matrice's inverse, but a translation's inverse() is its opposite (negative). Which is of course the correct mathematical operation.

[realthunder]

ah yes, I understand, of course. Soooo ... what about white listing Placement.multiply() and Placement.inverse() ?

Well, I can add number protocol to Placement too, just like matrix, so you can do something like

Code: Select all

Group.<<Box.>>.Placement * Group.<<$Cube.>>.Placement ^ -1

[DeepSOIC]

but a translation's inverse() is its opposite (negative).

you seem to have missed the second line in the function you quoted, which also acts on translation part of a placement.

see https://en.wikipedia.org/wiki/Transform ... r_graphics

[Zolko]

ah yes, I understand, of course. Soooo ... what about white listing Placement.multiply() and Placement.inverse() ?

Well, I can add number protocol to Placement too, just like matrix, so you can do something like

Code: Select all

Group.<<Box.>>.Placement * Group.<<$Cube.>>.Placement ^ -1

if these can be combined several times in any order, yes, functionnally that's perfect ( visually, multiply() and inverse() are nicer though ). Thank-you for your efforts.