Modifying the model is always a sync operation. Normally there is no need to care about the async nature of the interaction between Canvas and the server. For example:

figure.translate(10,0);
figure.rotateAround(figure.pin(),45);
figure.commit$();

On the other hand, if metrics are needed to define the values that you are going to change then we are in promises land. Getting metrics is an async operation in Canvas.
As every async operation in Canvas, metrics functions are marked with a trailing $ and will return a promise for the computed value:

figure.center$() .then(function(center){
figure.rotateAround(center,45);
figure.commit$();
});

Figure metrics

Pre metrics

The figure frame is computed transforming with the matrix the bounds of the untransformed figure. We call the metrics of the untransformed figure pre metrics. These metrics are needed for some operations like envelope equalization.

Global metrics

Grouped figures are then transformed by their parents matrix. Global metrics provide an easy way to know the final bounds of a figure even if they are grouped. If the figure is not grouped, global metrics will be equal to the normal metrics. The global version of the metrics are: globalMatrix$, globalBounds$, globalCenter$, globalFrame$, globalVectorBounds$, globalVectorFrame$, globalPreBounds$ and globalPreVectorBounds$.

Examples

[TODO]

Why metrics are async operations?

Canvas JavaScript engine (Cx) is unable to reproduce every operation supported by the CadWorX CadXEngine server. Only a subset of CDL documents can be completely handled locally. For example, a Text will need the server to process the fonts, generate the vector representation of the characters and arrange them to get to its final output vector shape representation. We call updating to the act of computing the figure’s output representation (composed of only simple shapes and raster figures). Because Cx may need the help of CadXEngine server, updating a figure is an asynchronous operation. Measuring geometry figure properties like bounds and frame requires the output of the figure to be up-to-date.

When using metrics, Canvas takes care of updating the figure behind the scene. Figure updating can also be triggered manually using:

figure.update$() .then(function(figure){
// ...
});

If you already know the figure is up-to-date, you can use synchronous versions of the metrics. The set of functions that needs the figure to be updated are marked with a trailing underscore sign, underscore so developers can easily identify them: bounds, frame, center_:

figure.update$() .then(function(figure){
var b = figure.bounds_();
var f = figure.frame_();
// ...
});

These may be useful in some contexts, but always go for the async version of the metrics first. Calling any metric_ function when the figure is invalidated (its output has not been updated) will result in an exception. As reference, internally metrix$ is implemented like:

metrix$: function(){
  return this.update$() .then(function(figure){
  return figure.metrix_(); 
  }); 
}