# Envision 3.0

November 14, 2024 - SHA: 4dfe82aa

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.

Envision for Web Envision for Desktop

## Fixed Bugs

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

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

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

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

### CAE-1415 VTU: Improved file identification

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

## New Features

### CAE-1396 Viridis Color Scheme

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

### CAE-1426 Support interpolated node results for QueryNodeInfo

`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

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

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/hoops/latest/envision-web/operators.html.

### CAE-1397 Strict mode in TypeScript

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

## Patches

### Envision 3.0.1

November 25, 2024 - SHA: ada9deda

#### CAE-1438 Fix ViewerPickHandler errors in example apps

Examples which are based on a front end framework were not working, due to the version 3.0 operator changes. This patch fixes the ViewerPickHandler imports and related errors everywhere.

Conversation saved
HOOPSY BETA

### Hello! I'm HOOPSY

Your multilingual generative AI assistant for documentation. Ask me anything about HOOPS Envision for Desktop in your own language, or choose a sample question below to start a conversation:

What is HOOPS Envision for Desktop?
What are the latest release notes for HOOPS Envision for Desktop?
How do I start evaluating HOOPS Envision for Desktop?
How do I write my first sample application?
How can I get assistance?

HOOPSY may store conversations according to OpenAI's policy. Responses may not always be accurate.

HOOPSY is thinking...