Envision 3.0

November 14, 2024 - SHA: 35e51d55

CEETRON Envision 3.0 is a major release which means it contains breaking changes. The main focus this release has been to upgrade our toolkit to use TypeScript’s strict mode, which enforces more rigorous type-checking and ensures higher code reliability and safety.

Note

Breaking changes in this release only affects Envision Web. There are no breaking changes for Envision Desktop.

See Breaking Changes at the bottom for a full description of changes.


web CEETRON Envision for Web desktop CEETRON Envision for Desktop

Fixed Bugs

CAE-1415 VTU/VTM: Added support for “frequency” web desktop

Added support for PVD files containing the “frequency” attribute also. Earlier, only “timestep” was handled.

CAE-1425 QueryElementInfo: validate user’s index against the valid index range web

Fixed a crash with cee.ug.QueryElementInfo() when using index identification

elementIdentType = RemoteQueryInputIdentType.INDEX

and querying an invalid element index.

CAE-1432 Fixed crash when opening file using the OpenFoam Data Provider web desktop

Fixed issue with crash due to non-threadsafe code in OpenFoam data provider plugin.

CAE-1415 VTU: Improved file identification web desktop

Expand file identification to validate VTU files with attributes in both single(’) and double(”) quotes.

New Features

CAE-1396 Viridis Color Scheme web desktop

This feature adds the popular Viridis color scheme to the list of available built-in color schemes within Envision.

../_images/cae1396.png

CAE-1416 Support interpolated node results for QueryNodeInfo web

cee.ug.QueryNodeInfo() now retrieves the node averaged scalar results when these are available, unifying the logic with the node result from picking.

Added a new property scalarResultIsInterpolated to cee.ug.QueryNodeInfoData().

CAE-871 Relative displacement scaling web desktop

Added an option to scale displacement results with a factor relative to the size of the model. A relative scaling factor of 1 means that the length of the largest currently loaded displacement will be equal to the maximum bounding box extent of the model.

In Envision Desktop:

void        DisplacementSettings::setScaleFactor(double scaleFactor, ScaleMode mode):
ScaleMode   DisplacementSettings::scaleMode() const;

where mode is ABSOLUTE_SCALING or RELATIVE_SCALING.

In Envision Web (an accessor):

get scaleMode(): DisplacementScaleMode
set scaleMode(scaleMode: DisplacementScaleMode)

where mode is DisplacementScaleMode.ABSOLUTE_SCALING or DisplacementScaleMode.RELATIVE_SCALING.


Breaking Changes

CAE-1370 Operators are the new default for handling user input web

We are deprecating the older user input handling and fully embracing Operators for all user interaction with the viewer. We are still keeping backwards compatibility for the time being, but in practice, the use of Operators is now opt-out, that means they are turned on by default. In case you are not ready to make the transition yet, you can disable the use of operators. We strongly recommend the use of Operators as it is the cleaner, more sustainable and modular approach to user-input handling in the viewer. Read more about Operator integration here: https://docs.techsoft3d.com/ceetron/latest/envision-web/operators.html.

CAE-1397 Strict mode in TypeScript web

With this release, our toolkit has been upgraded to use TypeScript’s strict mode, which enforces more rigorous type-checking and ensures higher code reliability and safety. In turn, this will help with catching potential bugs early in development and prevent many common errors, like using variables before they are defined or failing to handle null and undefined cases. Adopting strict mode was for us essential to improve code robustness, encourage best practices, and provide you with a more reliable and efficient toolkit in the long run.

We have clarified many scenarios where nullish values occur and unified the use of null and undefined across the board. As a general rule of thumb, we have adopted the usage of null for objects and undefined for value types.

What does that mean for you? If your application is not using strict mode, you can safely ignore the “Typing changes clarifying current behavior” section, as those changes are adding nullish types purely for clarifying how the method/member worked before. On the other hand if you were using strict mode already, you might see some errors pop up with regards to null and undefined types. We have clarified the documentation in the effort to explain the reason why those falsy values occur in that place.

In all cases, be sure to check out the “Possibly breaking behavioral changes” sections to see the changes that do not necessarily have to show up in the output of the TypeScript transpiler.

Global (cee)

Possibly breaking behavioral changes

  • Camera()
    • project(): changed failure return value from undefined to null

    • unproject(): now returns null instead of crashing if coordinate cannot be unprojected

  • Plane()
    • projectVector(): changed failure return value from undefined to null

  • ScalarMapperContinuousDomain()
    • aboveRangeColor: now accepts and returns null instead of undefined

    • belowRangeColor: now accepts and returns null instead of undefined

  • Viewer()
    • rayFromCssCoordinate(): now returns null on failure instead of returning a defunct Ray() object

Typing changes clarifying current behavior:

  • Background()
    • image: added null to return type

  • Camera()
    • fieldOfViewYDeg: added undefined to return type

  • CloudSession()
    • addViewer(): added null to return type

  • NavigationOperator()
    • rotationAxis: added null to return type

    • minWalkTargetDistance: added undefined to input and output type

  • Navigation()
    • minWalkTargetDistance(): added undefined to input and output type

  • Operator()
    • ownerView(): added null to return type

  • OperatorStack()
    • hotKeyOperator(): added null to return type

    • get(): added null to return type

  • ScalarMapperContinuous()
    • rangeMinimum(): added undefined to return type

    • rangeMaximum(): added undefined to return type

  • ScalarMapperContinuousPiecewise()
    • rangeMinimum(): added undefined to return type

    • rangeMaximum(): added undefined to return type

  • ScalarMapperFilledContours()
    • rangeMinimum(): added undefined to return type

    • rangeMaximum(): added undefined to return type

  • ScalarMapperFilledContoursUniform()
    • rangeMinimum(): added undefined to return type

    • rangeMaximum(): added undefined to return type

  • View()
    • rayIntersect(): added null to return type

    • getRayThroughPoint(): added null to return type


Remote Model (cee.ug)

Possibly breaking behavioral changes

  • ClientSideHitItem()
    • use null instead undefined if the intersectionPoint property is invalid

  • LegendColorMarker()
    • now an interface (previously was a class)

  • QueryAllElementResultsForFramePartData()
    • elementIds: is now null when id’s are not available (previously undefined)

    • nodeIds: is now null when id’s are not available (previously undefined)

  • QueryBulkCalculationValues()
    • regionTriangleVertices is now null when not including region triangles in the query (previously undefined)

  • RemoteModel()
    • modelSpec and modelDirectory are now always non-null, even before opening a model. Accessing the setters of modelSpec before the model is opened, will result in an error being thrown. Also please note that the references of the two objects will change after opening the model. This requires no change in your code if modelSpec() and modelDirectory is accessed in the usual way, inside or after the callback of the openModel() method. A new method isOpen() has been introduced to check whether the model has been opened.

    • createVisibleObjectPicker(): now returns null instead of a partially created picker on failure

    • createTrianglePicker(): now returns null instead of a partially created picker on failure

  • ScalarSettings()
    • aboveRangeColor and belowRangeColor changed their unset type to null (previously undefined)

  • VectorSettings()
    • anisotropicScaleFactor: unset type changed to null (previously undefined)

Server callback changes

We have clarified the typing when it comes to server callbacks. In practice, all the error arguments in the callback functions now add null to their types. Additionally, the type of the main data argument in callbacks is never defined as possibly falsy, but in case there is an error, the user of the function is responsible for handling it and not accessing the data. In such case, the data argument will be falsy, even though the type contract is not specifying falsy values. This is not a change in the current behavior and requires, besides updating the error typings, no further changes.

Example:

const query = new ug.ElementInfoQuery();
query.executeQuery(/* arguments */, (error: Error | null, data: QueryElementInfoData[]) => {
    if (error) {
        console.error(error);
        return;
    }
    // If there is an error and we would decide not to return after the error, data will be null here,
    // even though it is not typed as such.
    console.log(data);
});

List of callbacks where we added null to the type of the error argument:

  • ServerUpdateCompletedCallback()

  • PollForDataSourceChangesCallback()

  • DataSourceRequestCallback()

  • SendToCloudCallback()

  • CreateResultCalculatorCallback()

  • QueryBulkCalculationCallback()

  • QueryElementInfoCallback()

  • QueryPartResultsCallback()

Typing changes clarifying current behavior:

  • CuttingPlane()
    • filterScalarRangeMinimum: added undefined to the return type

    • filterScalarRangeMaximum: added undefined to the return type

  • CuttingPlaneProperties()
    • filterScalarRangeMinimum: added undefined to the type

    • filterScalarRangeMaximum: added undefined to the type

  • ModelDirectory()
    • getStateNameById(): added null to the return type

    • getStateReferenceValueById(): added undefined to the return type

    • getScalarNameById(): added null to the return type

    • getVectorNameById(): added null to the return type

    • getDisplacementNameById(): added null to the return type

    • getSetNameById(): added null to the return type

    • getPartNameById(): added null to the return type

    • getResultInfoByIdString(): changed the “not found” type on return from undefined to null

    • getResultIdStringById(): changed the “not found” type on return from undefined to null

  • ModelSettingsProperties()
    • transformationMatrix: added null to the type

  • ProgressData()
    • debugMessage: added null to the type

  • QueryElementInfoData()
    • scalarResult: added undefined to the type

    • elementNodes.scalarResult: added undefined to the type

  • QueryNodeInfoData()
    • scalarResult: added undefined to the type

  • RemoteModel()
    • getScalarResultMinimumValue(): added undefined to the return type

    • getScalarResultMaximumValue(): added undefined to the return type

    • getVectorResultMinimumLength(): added undefined to the return type

    • getDisplacementResultMinimumLength(): added undefined to the return type

    • getDisplacementResultMaximumLength(): added undefined to the return type

    • getPartSettingsById(): added null to the return type

    • getScalarSettingsById(): added null to the return type

    • getVectorSettingsById(): added null to the return type

    • getDisplacementSettingsById(): added null to the return type

    • getCuttingPlaneById(): added null to the return type

    • addIsosurface(): added null to the return type

    • getIsosurfaceById(): added null to the return type

    • addIsovolume(): added null to the return type

    • getIsovolumeById(): added null to the return type

    • getParticleTraceGroupById(): added null to the return type

    • clientSideRayIntersect(): added null to the return type

    • setResultRangeChangedHandler(): added null to the type of the callback argument to allow for a cleanup of the callback

  • ScalarSettings()
    • filteringRangeMinimum: added undefined to the type

    • filteringRangeMaximum: added undefined to the type

  • ScalarSettingsProperties()
    • filteringRangeMinimum: added undefined to the type

    • filteringRangeMaximum: added undefined to the type

    • aboveRangeColor: added null to the type

    • belowRangeColor: added null to the type

  • VectorSettings()
    • scaleFactor: added undefined to the type

    • clampingRangeMinimum: added undefined to the type

    • clampingRangeMaximum: added undefined to the type

    • filteringRangeMinimum: added undefined to the type

    • filteringRangeMaximum: added undefined to the type

  • VectorSettingsProperties()
    • scaleFactor: added undefined to the type

    • anisotropicScaleFactor: added null to the type

    • clampingRangeMinimum: added undefined to the type

    • clampingRangeMaximum: added undefined to the type

    • filteringRangeMinimum: added undefined to the type

    • filteringRangeMaximum: added undefined to the type


Constant Remote Model (cee.cug)

Possibly breaking behavioral changes:

  • ConstantRemoteModel()
    • getBoundingBoxForPart(): now returns an invalid bounding box instead of undefined if no bounding box is found

  • ColorLegend()
    • Removed from the public API of the cug module

Typing changes clarifying current behavior:

  • InitializationCompleteCallback()
    • added null to typing for err parameter

  • RayIntersectCallback()
    • added null to typing for the hitItem parameter to the callback function

  • ConstantRemoteModel()
    • simulationInfo: added null to return type

    • modelSpec: added null to return type

    • animation: added null to return type

    • getResultInfo(): added null to return type

    • rayIntersect(): added null to return type

    • setMasterModelForSyncAnimation(): added null to parameter typing

  • FrameInfo()
    • added undefined to return type for referenceValue, fringesMinimumValue and fringesMaximumValue

  • HitItem()
    • now exposed as an interface instead of a class

    • added null to typing for the nodePosition and intersectionPointNormal properties

    • added undefined to typing for the nodeScalarResult and elementScalarResult properties


Unstruct Surface Grid (cee.usg)

Possibly breaking behavioral changes:

  • HitItem()
    • now an interface

  • PartScalars()
    • getValueRange() now has the range min: Number.MAX_VALUE and max: -Number.MAX_VALUE when no meaningful values can be determined from the supplied value array.

  • PartVectors()
    • getVectorLengthRange() now has the range min: Number.MAX_VALUE and max: -Number.MAX_VALUE when no meaningful values can be determined from the supplied vectors array.

Typing changes clarifying current behavior:

  • HitItem()
    • added undefined to the typing of the properties elementId and closestNodeId

  • Mesh()
    • added null to the typing of elementTypeArray property

  • Part()
    • added null to the typing of mesh property

  • ScalarSettings()
    • added null to the typing of scalarMapper property

  • State()
    • added undefined to the typing of referenceValue property

    • added null to the typing of geometry property

    • added null to the typing of the return type of the getPartFringesAt() method

    • added null to the typing of the return type of the getPartDisplacementsAt() method

    • added null to the typing of the return type of the getPartTransformationAt() method

    • setters for Fringes, Vectors, Displacements and Transforms are now typed so that they accept null

  • UnstructGridModel()
    • added null to the typing of currentState property

    • added null to the typing of the return type of the rayIntersect() method


Geometry (cee.geo)

Typing changes clarifying current behavior:

  • GeometryModel()
    • transformationMatrix: added null to typing

    • rayIntersect(): added null to return type

  • HitItem()
    • intersectionPoint: added null to typing

  • MeshHitItem()
    • intersectionPoint: added null to typing

  • MeshIndexedLines()
    • textureCoordinates: added null to typing

  • MeshIndexedTriangles()
    • constructor(): added null to constructor parameter optionalVertexData input type

    • textureCoordinates: added null to typing

  • Part()
    • mesh: added null to typing

    • transformationMatrix: added null to typing

  • PartSettings()
    • specularIntensity: added undefined to typing

    • texture: added null to typing


Markup Model (cee.mrk)

Possibly breaking behavioral changes:

  • PartLabels()
    • getLabelOffsetPosition(): now returns null instead of undefined if no offset position is set

    • getLabelOffsetDirection(): now returns null instead of undefined if no offset position is set

Typing changes clarifying current behavior:

  • PartHitItem()
    • added null to typing for intersectionPoint property

  • PartPoints()
    • colorArray: added null to return type


Utilities (cee.utils)

Possibly breaking behavioral changes:

  • PathGenerator()
    • generateVerticesForCircleThrough3Points(): changed error return value from undefined to null

    • generateVerticesForCircularSegmentBetween2Lines(): changed error return value from undefined to null

Typing changes clarifying current behavior:

  • ManipulatorTrackball()
    • setRotationAxis(): added null to input type