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.
CEETRON Envision for Web CEETRON 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-1416 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/ceetron/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 fromundefined
tonull
unproject()
: now returnsnull
instead of crashing if coordinate cannot be unprojected
Plane()
projectVector()
: changed failure return value fromundefined
tonull
ScalarMapperContinuousDomain()
aboveRangeColor
: now accepts and returnsnull
instead ofundefined
belowRangeColor
: now accepts and returnsnull
instead ofundefined
Viewer()
rayFromCssCoordinate()
: now returnsnull
on failure instead of returning a defunctRay()
object
Typing changes clarifying current behavior:
Background()
image
: addednull
to return type
Camera()
fieldOfViewYDeg
: addedundefined
to return type
CloudSession()
addViewer()
: addednull
to return type
NavigationOperator()
rotationAxis
: addednull
to return typeminWalkTargetDistance
: addedundefined
to input and output type
Navigation()
minWalkTargetDistance()
: addedundefined
to input and output type
Operator()
ownerView()
: addednull
to return type
OperatorStack()
hotKeyOperator()
: addednull
to return typeget()
: addednull
to return type
ScalarMapperContinuous()
rangeMinimum()
: addedundefined
to return typerangeMaximum()
: addedundefined
to return type
ScalarMapperContinuousPiecewise()
rangeMinimum()
: addedundefined
to return typerangeMaximum()
: addedundefined
to return type
ScalarMapperFilledContours()
rangeMinimum()
: addedundefined
to return typerangeMaximum()
: addedundefined
to return type
ScalarMapperFilledContoursUniform()
rangeMinimum()
: addedundefined
to return typerangeMaximum()
: addedundefined
to return type
View()
rayIntersect()
: addednull
to return typegetRayThroughPoint()
: addednull
to return type
Remote Model (cee.ug)
Possibly breaking behavioral changes
ClientSideHitItem()
use
null
insteadundefined
if theintersectionPoint
property is invalid
LegendColorMarker()
now an interface (previously was a class)
QueryAllElementResultsForFramePartData()
elementIds
: is nownull
when id’s are not available (previouslyundefined
)nodeIds
: is nownull
when id’s are not available (previouslyundefined
)
QueryBulkCalculationValues()
regionTriangleVertices
is nownull
when not including region triangles in the query (previouslyundefined
)
RemoteModel()
modelSpec
andmodelDirectory
are now always non-null, even before opening a model. Accessing the setters ofmodelSpec
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 ifmodelSpec()
andmodelDirectory
is accessed in the usual way, inside or after the callback of theopenModel()
method. A new methodisOpen()
has been introduced to check whether the model has been opened.createVisibleObjectPicker()
: now returnsnull
instead of a partially created picker on failurecreateTrianglePicker()
: now returnsnull
instead of a partially created picker on failure
ScalarSettings()
aboveRangeColor
andbelowRangeColor
changed their unset type tonull
(previouslyundefined
)
VectorSettings()
anisotropicScaleFactor
: unset type changed tonull
(previouslyundefined
)
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
: addedundefined
to the return typefilterScalarRangeMaximum
: addedundefined
to the return type
CuttingPlaneProperties()
filterScalarRangeMinimum
: addedundefined
to the typefilterScalarRangeMaximum
: addedundefined
to the type
ModelDirectory()
getStateNameById()
: addednull
to the return typegetStateReferenceValueById()
: addedundefined
to the return typegetScalarNameById()
: addednull
to the return typegetVectorNameById()
: addednull
to the return typegetDisplacementNameById()
: addednull
to the return typegetSetNameById()
: addednull
to the return typegetPartNameById()
: addednull
to the return typegetResultInfoByIdString()
: changed the “not found” type on return fromundefined
tonull
getResultIdStringById()
: changed the “not found” type on return fromundefined
tonull
ModelSettingsProperties()
transformationMatrix
: addednull
to the type
ProgressData()
debugMessage
: addednull
to the type
QueryElementInfoData()
scalarResult
: addedundefined
to the typeelementNodes.scalarResult
: addedundefined
to the type
QueryNodeInfoData()
scalarResult
: addedundefined
to the type
RemoteModel()
getScalarResultMinimumValue()
: addedundefined
to the return typegetScalarResultMaximumValue()
: addedundefined
to the return typegetVectorResultMinimumLength()
: addedundefined
to the return typegetDisplacementResultMinimumLength()
: addedundefined
to the return typegetDisplacementResultMaximumLength()
: addedundefined
to the return typegetPartSettingsById()
: addednull
to the return typegetScalarSettingsById()
: addednull
to the return typegetVectorSettingsById()
: addednull
to the return typegetDisplacementSettingsById()
: addednull
to the return typegetCuttingPlaneById()
: addednull
to the return typeaddIsosurface()
: addednull
to the return typegetIsosurfaceById()
: addednull
to the return typeaddIsovolume()
: addednull
to the return typegetIsovolumeById()
: addednull
to the return typegetParticleTraceGroupById()
: addednull
to the return typeclientSideRayIntersect()
: addednull
to the return typesetResultRangeChangedHandler()
: added null to the type of the callback argument to allow for a cleanup of the callback
ScalarSettings()
filteringRangeMinimum
: addedundefined
to the typefilteringRangeMaximum
: addedundefined
to the type
ScalarSettingsProperties()
filteringRangeMinimum
: addedundefined
to the typefilteringRangeMaximum
: addedundefined
to the typeaboveRangeColor
: addednull
to the typebelowRangeColor
: addednull
to the type
VectorSettings()
scaleFactor
: addedundefined
to the typeclampingRangeMinimum
: addedundefined
to the typeclampingRangeMaximum
: addedundefined
to the typefilteringRangeMinimum
: addedundefined
to the typefilteringRangeMaximum
: addedundefined
to the type
VectorSettingsProperties()
scaleFactor
: addedundefined
to the typeanisotropicScaleFactor
: addednull
to the typeclampingRangeMinimum
: addedundefined
to the typeclampingRangeMaximum
: addedundefined
to the typefilteringRangeMinimum
: addedundefined
to the typefilteringRangeMaximum
: addedundefined
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 forerr
parameter
RayIntersectCallback()
added
null
to typing for thehitItem
parameter to the callback function
ConstantRemoteModel()
simulationInfo
: addednull
to return typemodelSpec
: addednull
to return typeanimation
: addednull
to return typegetResultInfo()
: addednull
to return typerayIntersect()
: addednull
to return typesetMasterModelForSyncAnimation()
: addednull
to parameter typing
FrameInfo()
added
undefined
to return type forreferenceValue
,fringesMinimumValue
andfringesMaximumValue
HitItem()
now exposed as an interface instead of a class
added
null
to typing for thenodePosition
andintersectionPointNormal
propertiesadded
undefined
to typing for thenodeScalarResult
andelementScalarResult
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 propertieselementId
andclosestNodeId
Mesh()
added
null
to the typing ofelementTypeArray
property
Part()
added
null
to the typing ofmesh
property
ScalarSettings()
added
null
to the typing ofscalarMapper
property
State()
added
undefined
to the typing ofreferenceValue
propertyadded
null
to the typing ofgeometry
propertyadded
null
to the typing of the return type of thegetPartFringesAt()
methodadded
null
to the typing of the return type of thegetPartDisplacementsAt()
methodadded
null
to the typing of the return type of thegetPartTransformationAt()
methodsetters for Fringes, Vectors, Displacements and Transforms are now typed so that they accept
null
UnstructGridModel()
added
null
to the typing ofcurrentState
propertyadded
null
to the typing of the return type of therayIntersect()
method
Geometry (cee.geo)
Typing changes clarifying current behavior:
GeometryModel()
transformationMatrix
: addednull
to typingrayIntersect()
: addednull
to return type
HitItem()
intersectionPoint
: addednull
to typing
MeshHitItem()
intersectionPoint
: addednull
to typing
MeshIndexedLines()
textureCoordinates
: addednull
to typing
MeshIndexedTriangles()
constructor()
: addednull
to constructor parameteroptionalVertexData
input typetextureCoordinates
: addednull
to typing
Part()
mesh
: addednull
to typingtransformationMatrix
: addednull
to typing
PartSettings()
specularIntensity
: addedundefined
to typingtexture
: addednull
to typing
Markup Model (cee.mrk)
Possibly breaking behavioral changes:
PartLabels()
getLabelOffsetPosition()
: now returnsnull
instead ofundefined
if no offset position is setgetLabelOffsetDirection()
: now returnsnull
instead ofundefined
if no offset position is set
Typing changes clarifying current behavior:
PartHitItem()
added
null
to typing forintersectionPoint
property
PartPoints()
colorArray
: addednull
to return type
Utilities (cee.utils)
Possibly breaking behavioral changes:
PathGenerator()
generateVerticesForCircleThrough3Points()
: changed error return value fromundefined
tonull
generateVerticesForCircularSegmentBetween2Lines()
: changed error return value fromundefined
tonull
Typing changes clarifying current behavior:
ManipulatorTrackball()
setRotationAxis()
: addednull
to input type