docs: explain mxGraph perimeter and projection

docs/contributors/mxgraph-integration.md

@@ -137,6 +137,193 @@ Check the [GitHub Pull Request #291](https://github.com/process-analytics/bpmn-v
 to see various positioning methods in action.
 
 
+#### Terminal points and perimeter
+
+**Note**: all SVG files from this paragraph are generated from this [draw.io file](resources/mxGraph-perimeter.drawio)
+
+
+QUESTION: dans un fichier dédié car il commence à etre très gros
+
+
+intro mxgraph support of perimeter
+ensure that the terminal waypoints of the edge are on the shape border, never inside or outside the shape.
+TODO put screenshots directly here for illustration?
+
+floating point
+concept of port: another shape can be used to determine where the terminal point are put. Use case: inner elements, 
+fine for editor, not always accurate for visualization when the terminal point coordinates are provided
+perimeter: function defining how ... Several flavor available out of the box: rectangle, ellipse, diamond. Everything we need for BPMN shapes
+use next point: the last point defined in the array
+
+
+way mxgraph manage terminal points recomputation.
+If no perimeter set (not what we use): terminal are always at the center of the bounds defined by the perimeter
+If perimeter is set, use the latest point and project it to the perimeter when STYLE_ORTHOGONAL set to true (default to false) 
+or use Segment Connector for instance otherwise, compute the intersection of the segment between the shape center and the
+point with the perimeter and add the resulting points to the waypoints list.
+
+The following screenshots are done without STYLE_EDGE and STYLE_ORTHOGONAL set to false
+
+Orthogonal projection activation: style[mxgraph.mxConstants.STYLE_ORTHOGONAL] = 1;
+
+
+
+TODO store screenshots with projection from https://github.com/process-analytics/bpmn-visualization-js/pull/1765 (2 screenshots at the end)
+in the repo for offline browsing + rename visual test screenshot
+
+Screenshots done using visualization test diagram `flows.sequence.04.waypoints.03.terminal.outside.shapes.02.segments.no.intersection.with.shapes.bpmn`
+
+| without projection                                                                                                                    | Default (Projection to center)                                                                                                                                                  | orthogonal projection                                                                                                                                                    |
+|---------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| ![](images/mxgraph-perimeter/flows.sequence.04.waypoints.03.terminal.outside.shapes.02.segments.no.intersection.with.shapes-snap.png) | ![seq_flow_outside_no_segment_connector_01_default_projection_to_center](https://user-images.githubusercontent.com/27200110/150537056-68d7410b-9675-4bcc-9d01-ce2562965ffc.png) | ![seq_flow_outside_no_segment_connector_02_orthogonal_projection](https://user-images.githubusercontent.com/27200110/150537058-65e645c1-fb80-4f54-8da9-b0c819bbbc7a.png) |
+
+TODO au début? 
+We have a lot of non regression visual tests on associations, message and sequence flows for
+- terminal waypoints inside and outside shapes
+- outside without intersection of the flow segment with the shape
+
+
+
+voir aussi https://jgraph.github.io/mxgraph/javascript/examples/orthogonal.html
+début d'explications sur le fonctionnement dans PR "[TEST] Add more visual tests for edges #1399"
+j'ai maj l'issue des segment Connector:
+est-ce qu'avec mxgraph 4.2.2 ce n'est pas mieux --> non c'est pire, voir issue 994 et pr de poc
+
+orthogonal edges et issues liées : issue 994: voir suivi du 11/06/2021
+
+TODO schema of various projection on perimeter for explanation (principles of the computation)
+also add schema of the intersection solution
+
+TODO link to code in mxgraph 4.2.2 and even js code extract
+
+TODO check if there is technical information about this topic in the txt file in mxgraph src/ 
+
+code explanation about mxgraph terminal waypoints
+
+points definition from the model copied into the `abspoints` array property of the edge `state` instance
+and also add to `null` values at the beginning and the end of the array: they will later be replaced by the computed terminal points.
+**TODO ref to mxgraph code** computed by mxGraphView.getFloatingPoint
+
+special case: no waypoints, then the array contains 2 `null` values.
+computation: 1st computation: use the center of the other shape? find what is used as next point in this case
+result intersection on the 2 shapes with the segments from the 2 shape centers
+
+si pas de perimeter, point terminal est le centre de la shape
+retrouver le code
+explique pourquoi on avait issue sur les edges: pas de perimeter --> centre du edge pour les associations des text annotation (mettre l'issue)
+
+calcul des points terminaux
+cf https://github.com/process-analytics/bpmn-visualization-js/pull/1863 POC custom qui les change
+
+mettre des schémas et expliquer comment ca se passe les périmètres, et les projections vers centre (defaut) ou orthogonal
+(ce qui est activé avec SEGMENT_CONNECTOR et autre option)et ce qu'on voudrait nous:
+par défaut, pas une projection mais une prolongation vers l'intersection.
+Si pas d'intersection, faire la projection
+decrire ce qui a été fait dans en 0.23.0 en attendant + lien vers issue next
+
+
+le style orthogonal est passé à getPerimeterPoint dans mxGraphView et c'est la fonction de perimeter qui l'utilise
+
+
+référencer les issues concernées (orthogonal) info dans 
+https://github.com/process-analytics/bpmn-visualization-js/issues/349
+https://github.com/process-analytics/bpmn-visualization-js/issues/295
+https://github.com/process-analytics/bpmn-visualization-js/issues/295#issuecomment-904336449
+
+
+style config perimeter: par defaut, toutes les shapes ont un rectangle perimeter
+cf création du style par défaut par mxgraph (trouver la classe)
+
+mxConstant.STYLE_ENTRY_PERIMETER: 'entryPerimeter'
+Defines if the perimeter should be used to find the exact entry point along the perimeter of the target
+Possible values are 0 (false) and 1 (true).
+Default is 1 (true). Value is “entryPerimeter”.--> checker ou dans le code s'est utilisé
+voir aussi https://stackoverflow.com/a/62127707/14299521 pour des options
+il ya aussi les options pour décaler comme essayer par Céline dnas issue sur end event https://github.com/process-analytics/bpmn-visualization-js/issues/188
+
+parler aussi de STYLE_PERIMETER_SPACING (et de source/target spacing) dans le calcul du floating point
+permet d'avoir un border (possibiltié d'avoir des valeurs source/target qui s'ajoute a la valeur global)
+pourrait etre interessant pour le pb des end events: TODO mettre l'info dans l'issue mais dire attention code custom chez nous pour gérer les perimeters
+
+see also exit and enter style setting
+this is used by the perimeter function? if true, replicate the behaviour everywhere
+
+
+### Impact on marker
+
+issue PR sur pb conditional not always filled? 
+TODO lien 1er PR suppr orthogonal segment + test showing we always fill the marker and the msg flow start marker as well 
+
+arrow when extra terminal segment added
+- inside arrow: issue association https://github.com/process-analytics/bpmn-visualization-js/issues/715
+- arrow glitch when original terminal point is outside
+
+REASON: marker built by using the latest segment of points (TODO link code to confirm this)
+mxConnector.createMarker calcule la norme et son inverse
+c'est lui qui calcule le point dans le prolongement de celui avant/après qui correspond à la longueur du marker
+se base sur les points calculés avant pour finaliser les points du edge
+
+
+
+TODO add schema of current pb (glitch + inner original terminal point)
+
+
+
+
+### Current implementation to fix the problem
+
+explication du fix actuel
+dedicated mxGraphView injected in the BpmnGraph (extend mxGraph object)
+override the getFloatingPoint implementation
+
+si pas de waypoint, fallback perimeter qui fonctionne très bien
+si waypoints, on ne fait pas de calcul, on prend les derniers points non null du tableau (les originaux) et on les utilise
+directement comme points terminaux
+
+
+### Wish
+
+proposal to use intersection instead to extend or reduce the existing the segment and avoid this effect
+
+TODO schema of the intersection solution
+
+management when no intersection: fallback to mxgraph perimeter (see screenshots at the begining of the paragraph)
+
+### Others (TODO order)
+
+
+next to implement
+- "Ensure that the terminal waypoints are on the shape perimeter" https://github.com/process-analytics/bpmn-visualization-js/issues/1870
+- "Restore the experimental pools/subprocess live collapsing" https://github.com/process-analytics/bpmn-visualization-js/issues/1871
+
+
+Alternative
+
+décrire aussi les positionnements en foreground shape/edge: cf https://github.com/process-analytics/bpmn-visualization-js/pull/1863
+comme bpmn-js + transparency (impact on custom colors that would required to be transperent)
+only work for inner terminal waypoints
+--> don't want to implement this
+cf aussi issue 1870
+
+Info about SVG Q (quadratic): see PR 1207 (pb position overlay on edge center)
+a priori, created by mxPolyline.paintLine when rounded is true in the edge style, see mxShape.addPoints
+
+mxGraphView peut calculer des relative and absolute  coordinate as mxPoint with the edge mxState
+
+
+### INFOS a supprimer quand fini
+
+already considered
+- PR 1765
+
+issues without info
+- 349
+- PR 351
+- PR 388
+- 1236
+
+
+
 ## Overlays
 
 We are hacking mxCellOverlays which originally only supports image shape. This lets us use custom shapes.

docs/contributors/resources/mxGraph-perimeter.drawio

@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2022-04-06T13:05:08.207Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/17.2.4 Chrome/96.0.4664.174 Electron/16.1.0 Safari/537.36" etag="epoizijUXisM-Gp8Z8wd" version="17.2.4" type="device" pages="7"><diagram id="RNMhzFc4bVhtCsQH0jFF" name="context">7Vddk5owFP01PjojBFl9VNduH9qZ7thOp48puUJqIDQEhf31DZAAQddZbe33E8m5yb0395x8MEKruHgQOI3ecgJs5E5IMUL3I9d10HSiPhVSNsh8PmuAUFCiB3XAhj6BBvW8MKcEMmug5JxJmtpgwJMEAmlhWAh+sIdtObOjpjiEI2ATYHaMfqRERg06c+86/DXQMDKRHX/eWD7jYBcKnic6XsITaCwxNm70GrMIE37oQWg9QivBuWxacbECVpXVVKyZ9+oZa5uygES+ZEJePvrRbrkOPmDicVz6T1/ej1HjZY9Zrkuhk5WlqQ0kZFGVWPXq1aFlJGOmeo5q1kuHKsJE9TIp+K6tIFLIcZI6byAWIzrlB+AxSFGqAYeOB6OuqEeBwQQwLOne5hFrOYStuzbCO05VJu7ESNfTfrRwHX9iu8h4LgLQs/rVHThyB468gR+JRQjyyI9q9FbdQTV3F/Do3ZBH90/g0a7+tSw66LyfG7M4/aEs/u6ctSej2Xt3/pV7Dw03sf9TafP/Mdqc89W+mrYh/8/QpgqJy96wtBqQfS+x4zdivJ1Nufs422ymwX5MPp28HX2myrnc8nolHcP+15wbwzirHzgLNcDx0qIzqlaov7UXagD1Nkihet8ozkEYs8qZDqcorIlt4IHQJBTSVldzmK8446JT35YyNoAwo2GiujoHtNyDkFS9kRbaEFNCqjDLQ0QlbFIcVDEP6kX4cg1XPqE4q2KjjsGR7sx1v6dy/4TK0eDI7gva0selYjh1xTacELof0nQjfaQgqFrNhRJpYSvRv1Y4nm8Jx/3Fujl1qd9EJPX98P/oqI4KSwDIuZUAVLf7f2sune7/GK2/AQ==</diagram><diagram name="center projection" id="7wKxT-a-TJRUQJqu_FCP">7ZZbb5swFMc/DY+TwE5zeVzSLpN2UaZOmvY0ufgUrBgbmUMu+/Qz2IRLtq5J00qd9gT+c/w35/yODQFdZLulYXn6SXOQAQn5LqDXASERvQrtpVL2TpnNpk5IjOA+qBVuxU/wop+XlIJD4TQvodYSRV70ZsdaKYixpzFj9LYfdq9lf9WcJXAk3MZMHqvfBMfUqVMyafX3IJK0WTkaz9yTOxavE6NL5ddTWoF7krHGxidUpIzrbUeiNwFdGK3R3WW7BciqrE3FZprh9/nnL2pOUWK83C7NhzfO7N0pUw7JGVB4WWvirDdMlr6SPlfcN6UFxd9WhOyoLg6dp5hJO4rsbV05qFYI7ahAo9cHANQqj3xznyHwHmWfxxJ0Bmj2NmDbsm06Nu1gbTQDkqHY9HuD+RZLDnaHFVZa2NcjYbMdRt7Hb4ZoHPYtCl2aGPysbskHRmRgNBr4IDMJ4JGPvelk3Uo10BPg0meES14r3AGSc9FG9GGfZ0Y7uijaVwmSENrfpRN65i6lA6MxfVGWV/9Z2m35MIKzWQ6b4g8sbXXZvhOWVwHFE2l/LfP1j/XdNL4X1yr9yFbFxviP9Im0OSvSmnDUR1/pK4YIRtUKCelvT+p/oEX+duA+vkMGH/fJpU5uO2x/Bl14+7NNb34B</diagram><diagram name="orthogonal projection" id="5u9HompIC729Kqdd-Od9">7ZZdT8MgFIZ/TS9NWtimvdQ550c0S5Zo4h2WY2mkZVL2+eulha6l83PZTGa8Grw9vKfnPMDq4X66GEoyYbeCAveQTxcePvcQCnDX1z+FsjRKGJ4YIZYJtUG1ME5WYEW7Lp4mFHKjWUkJwVUyyZ3VkcgyiJSjESnF3A17FtzNOiExbAjjiPBN9SGhihn1BB3X+iUkMasyB73QPHki0UssxTSz+TKRgXmSksrGFpQzQsW8IeGBh/tSCGVG6aIPvGhr1bGbV3591Q2fwjvGxOpePfYH/pExu/jJknVxEjK1W2tkrGeET20nba1qWbUWMnpaENKzsjn4jKmU61mgh2XnoMjg61mupHhZA8Ba+eab2wqBOpRtHUMQKSi51AHzmm21Y1kDa6VJ4EQlM3dvELvF4rXdOsNIJPr1kF8dh8rHHoag57sWuZjKCOyqZstbRqhl1Gn5KCJjUBs+etCoupZKoD+Ai/cIFx0q3I6LZFu0Af7cZ89oOztFe5AgEcLuKT3GW55S3DLq4V9l2f1nqY/l5wi2ZtneFB+w1N0ly0bYpAjI90G7tw1tSnJWEg5c9IU+IkqBzEoF+fjdm/oPbJGvLtxvX9xh68892NXNraf1x6AJrz+28eAN</diagram><diagram name="marker positionning" id="hUysYIEV5oSPOwoVvPX7">5VbbjpswEP2aPCYCmyTksbl0W6mrRo321jcXJuDG4Mg4IfTra7C5ONlLibpSpT7BHI+PmTlngAFeJKcbQfbxLQ+BDZATngZ4OUDIxWNHXUqk0Mhs5msgEjQ0SS2wob/AgGZfdKAhZBozkOScSbrPrN0BT1MIpIURIXhup205s0/dkwgugE1A2CX6QEMZa9RH0xb/BDSK65PdyUyv/CDBLhL8kJrzUp6CXklITWMKymIS8rwD4dUALwTnUt8lpwWwsq11x777if/F263H29Xd5+H9Zr5+QENN9rHPlqY4Aan8u9RIUx8JO5hOmlplUbcW0vBDqZCKqubgeSwTpiJX3Vadg/IER0WZFHzXCIAV8odPbiqE0FLZ1HEDPAEpCpWQt9rWjo07staYAEYkPdreIMZiUUPXnLDmVD0ecsw4YMfwmGHAnmNTZPwgAjC7ui0/I/LOiBor1USSiAjkBZG66ZTdQpWiz6t73N2uJsHd12/JYfrzcXifr0RWt7WfuiHJ4kpR15a6xNdEShBphSAHX0iOLiyhdBfFo6GogqdyZTSuw+Wpm7ksTNTPOLqPr3TC+acMhjzbF+7sSoPhMyJ0TvTOBnPeNpgUlKRRGc3zmErY7ElQLuXqQ2QbbMtTab4srlcZSaom89JtuLTLljK24IyL1qv9XHIEIeH0qv61QP4Lg9vxh/+MPybeCE1edoPV/r69fs9XNepOqjPy/LE9rd4UvzGvVbQGQVWxIP6LIT5/uY+vHGI0vW6IldSk6KTty4Ss35irsP2B0entDyJe/QY=</diagram><diagram name="marker rendering" id="KBc98q3cc0dlVpS0iDJ2">zVXRbpswFP0aHlsRGxLyuKRdp0mV2CK126MLt2DV2MiYAPv62dgESNa1TJu0vMT3XPuYe8694OF90d5JUub3IgXmIT9tPXzjIbTCoa//DNJZZLuNLJBJmrpNI3CgP8CB7lxW0xQqizlICcEULavZ6URwDomaYURK0cy3PQs2v7UkGVwAh4SwS/SRpiq3aIQ2I/4JaJYPN6/WW5t5IslLJkXN3X1ccLCZggw0rqAqJ6loJhC+9fBeCqHsqmj3wIysg2L8igbZ/dfPDw+PdYxiGkVf4itL9nHJkVNxErj6u9TIUh8Jq52SrlbVDdICTz8Yh3TUi4N3uSqYjlZ62SsH5gZfR5WS4uVkANbIO5/cVQjpzGVXxx2IApTs9IZm9Hbo2Hxi64BJYETR47w3iGux7ER3uiEWVD8e8t04YN/xuGHAgT+nqEQtE3CnppKfEQVnRKdWGogUkRmoCyK9mJQ9Qr2jC9wN3nZXSUp4ZqJdk1MFh5IkJtXo98Tc6mfBlRv8VdBbr7TIghunQ5OnjO0FE7In1hqa3+IWOIJU0P62CVwWRa+IO2mS6BdNsg6u0fr1lph5sFTw8B+Ok5ZipyWU3TeTvg6icAC+W2CDB+CmdQw26qZRDJLqYkE6cJk9tmHfbrn/ZJLR+QCGfzjJaHNGtH3fJGurSTfZVpoN1bJZ1+H4kbHbx484vv0J</diagram><diagram id="ne7omDIuoBgSVefN5mzM" name="no intersection">7VlNc9owEP01HNuxJJvAMZA07XQ6yZSmzOQmbIGVCMsji6/++kpYxpZwAiUF4klOWM/SSnpvdyXWLdSfLm8ETuMfPCKsBb1o2UJXLQgBgIH60cgqRzoI5sBE0Mh0KoEB/UMM6Bl0RiOSWR0l50zS1AZDniQklBaGheALu9uYM3vWFE/IFjAIMdtGhzSSsdkFvCjxr4RO4mJm0O7mb6a46Gx2ksU44osKhK5bqC84l/nTdNknTJNX8JKP+/LM283CBElkzYD7jIjb0aPmBHoMj5Qu6075sMLK7dWQ+hfD+PLmV/e+/zRZDr7NP8HN6jazZnJVMLKIqSSDFIe6vVCqt1AvllNtHqhHnKW5DmO6JGqW3pgy1ueMC4UlPFGjetkTkaFmx1MNoxwerSfQSL7EORGSLJ/dLKgs8obwKZFipbqYAbBjWC/czjQXFQ0NFFfkKzBsvGayMVwSqx4MLUWzQnW9VrUsmz3NMZuRqjSvoNqmUndJiaBqB0STz+iYMJqQuxL7H1SfjOn9aEW7aSVJdKlTQ+mQFVIFnyWRZrPiiiTaShI72ansP6jZf4EJwrCkc9t8HSlmhjtOE1nxc2SzDwKH14zPREjMqGo6cQyBtm3ItSOxmBC5ZWct0WbXh6vmH6JahLN4rRSwJdT4HZbKw5M1Aj2kk44U/GmTxOH7lRpBxxA8mta/RYi86OHnVa/b+f4YXj6sktE+ie+taK0WtSZ1Vxo/l090A0vJizcf/LUOcVDwNzZl+8AmG/mHxrFvG4KuoSPLFjQnjhuvdeA5hsBptW5/aL1La+R5n8HLIjUlsrvvKiEHXec+1D40SJ2LlWvn2PeqBl2szpaQO26QAtRQteEeajNG00yr/K+VBKtCU1PBMXO/pm7gO4UDWIRhxRP8Gk9wc+EhlYN6RjsNZ9QtxZyf0T0OEhHz6WiW7WZ0F4FHqSO2nX9GAJyZ0iLpfCT5ExzobSegts6KI+d4uMeJ/rbjxz9d/Khm+TElV6D8JIWu/wI=</diagram><diagram name="projection vs intersection" id="MDurigiudHay89gO_hJH">7VhRb5swEP41eWxkbCDJY5u06TZVi5JJbZ8mFxywCpgZp4T9+hkwAUO2LDRpVW1P4T7bd/F93/kMAzQNt3OOY/+OuSQYQOBuB2g2gNAwoCV/ciQrkTGCJeBx6qpJNbCiP4kCgUI31CVJiSlIMBYIGifaaodFEXGEhmHOWapPW7NAjxpjj3SAlYODLnpPXeGrXcBRjd8S6vlVZMOelCNP2Hn2ONtEKl7EIlKOhLhyozaU+NhlaQNC1wM05YyJ8incTkmQp7XK2PwL/jyylpNovdykdgLi+wvnonR2c8yS3eY4icRpXSuWX3CwUZlUexVZlVoSuZc5Q9IqkoOufBEG0jLkY5E5kkcA0koEZ887ApBESm/E7bB3YCvGLr9SsoSFRPBMrktrbi3Fit+gtcI4CbCgL3pMrCTm7dztIiwYlf8GgqocJsqPKgaIgO4iYRvuELWqmfKWI4R0R3bLj8DcI6LjRz40dl1DBaFHkIv6kOvixC8INXSmc3yBhSA8KhAIUIdx2FGEZJlnD8pFYTzmI0OrMmfb5sxZpqxX6UaePUVi/zDPfFd9tWQx7ikv2PJjtB2dWV/mYX0JTnHk5dZV6lNBVjF28qFUtiFdX2sWCdVXDLPQkZA5ZrnYUK6WNQ2CKQsYr6WqwhMuyLaHTLr0V15GrbxWXa4hj/EeedjmENq/F4OW/mNzbZ3xoIbNQgVDc2zpxWqO0IFyLawF4VRulvB/oYZbLcIwe9awYferYck0zhrT4nxC8soq92++f/IexDK8xLff7hZzy//xVd0q/l8RNNoseKIrgm2/1RVhL7nG+18RPib/5onq3zp0kJxZAH/xAnCSHg72t3D1PoifimDgjE3dAq1Eg/FbNvW9ye91QT+iqX/I0jLhqUrrUI2esbVKs/4wUE6vP7yg618=</diagram></mxfile>