Releases: iTwin/itwinjs-core
v4.9.0
deltaDoc: true
version: '4.9.0'
4.9.0 Change Notes
Table of contents:
Quantity
- The
minWidthproperty on FormatProps now works as documented. - The
spacerproperty on FormatProps now indicates the space used between composite components, it defaults to a single space, and there is no longer a ':' prepended. If a ':' spacer is desired,spacerhas to be set accordingly. This is to streamline the behavior with the documentation and native APIs. - Added support for bearing and azimuth format types (e.g. bearing
N45°30'10"E). A new phenomenon "Direction" for these will be added to our units library soon, but they work just as well with the angle phenomenon for now. Persistence values for both bearing and azimuth are to be provided counter-clockwise from an east-base (inspired by PowerPlatform).
Electron 32 support
In addition to already supported Electron versions, iTwin.js now supports Electron 32.
Geometry
Approximating an elliptical arc with a circular arc chain
Arc3d.constructCircularArcChainApproximation returns a CurveChain of circular arcs that approximates the elliptical instance arc. Each arc in the chain starts and ends on the ellipse. The ellipse major/minor axis points and tangents are also interpolated, as well as those at the elliptical arc start/end, and the arcs are arranged to preserve ellipse symmetry. Various settings in the optional EllipticalArcApproximationOptions input object control the approximation accuracy. The default method is EllipticalArcSampleMethod.AdaptiveSubdivision, which is controlled by a maximum error distance, options.maxError. Other values of options.sampleMethod interpolate the ellipse in other ways, controlled by the number of points interpolated in a given quadrant, options.numSamplesInQuadrant. For a fixed number of samples, the default method usually yields the most accurate approximation.
Pictured below in order of decreasing error are some example approximations in blue, with ellipses in black, sample sites circled, and maximum error segment in red.
Approximation using options.sampleMethod = EllipticalArcSampleMethod.UniformCurvature and options.numSamplesInQuadrant = 5, yielding error 0.18:
Approximation using options.sampleMethod = EllipticalArcSampleMethod.UniformParameter and options.numSamplesInQuadrant = 5, yielding error 0.12:
Approximation using options.sampleMethod = EllipticalArcSampleMethod.NonUniformCurvature, options.remapFunction = (x) => x*x, and options.numSamplesInQuadrant = 5, yielding error 0.05:
Approximation using options.sampleMethod = EllipticalArcSampleMethod.AdaptiveSubdivision and options.maxError === 0.05, yielding error 0.03:
Triangulating points
PolyfaceBuilder.pointsToTriangulatedPolyface, which creates a Polyface from an xy-triangulation of input points, now uses the StrokeOptions input setting options.chordTol to control the maximum xy-distance for equating points. This method preserves the highest z-coordinate among points equated in this manner. The default for this setting is Geometry.smallMetricDistance, however for typical DTM datasets, a larger tolerance can be used (e.g., 1-2mm) to eliminate extraneous "skirt" points that lie underneath the terrain boundary.
Pictured below are triangulations of a DTM dataset with skirt points. At top is the result using default tolerance. Due to the skirt points having xy-distance greater than the default tolerance from actual terrain sites, they are included in the triangulation, resulting in undesirable near-vertical facets. At bottom is the result using options.chordTol = 0.002, which is sufficiently large to remove these artifacts:
Display
Dynamic clip masks
PlanarClipMaskSettings permit you to mask out (render partially or fully transparent) portions of the background map based on its intersection with other geometry in the scene. Previously, only GeometricModels and reality models could contribute to the mask. Now, geometry added to the scene dynamically via TiledGraphicsProviders can also contribute to the mask. As with reality models, TiledGraphicsProviders' geometry only contributes to the mask in PlanarClipMaskMode.Priority. You can optionally configure a custom mask priority using TileTreeReference.planarClipMaskPriority or the newly-added RenderGraphicTileTreeArgs.planarClipMaskPriority. Here's an example of the latter:
[[include:TileTreeReference_DynamicClipMask]]Presentation
Custom content parser for creating element properties
The getElementProperties function on the backend PresentationManager has two overloads:
- For single element case, taking
elementIdand returning an data structure in the form ofElementProperties. - For multiple elements case, taking an optional list of
elementClassesand returning properties of those elements. While the default form of the returned data structure isElementProperties, just like in single element case, the overload allows for a custom parser function to be provided. In that case the parser function determines the form of the returned data structure.
In this release the overload for single element case was enhanced to also take an optional custom content parser to make the two overloads consistent in this regard. In addition, the getElementProperties method on the frontend PresentationManager has also been enhanced with this new feature to be consistent with the similar method on the backend.
ECExpression to get related instance label
A new GetRelatedDisplayLabel function symbol has been added to ECInstance ECExpressions context, allowing retrieval of related instance label. The function takes 3 arguments: full name of a relationship, its direction and related class name. Example usage in calculated properties specification:
{
"label": "My Calculated Property",
"value": "this.GetRelatedDisplayLabel(/"BisCore:ModelContainsElements/", /"Backward/", /"BisCore:Model/")"
}The above specification, when applied to BisCore:Element content, will include a "My Calculated Property" property whose value equals to the label of the model that contains the element.
Referencing schema-based categories in property overrides and calculated properties
In some cases there may be a need to place specific property in the same group as other specific properties. One way to do that is by creating a property category specification and assigning it to all such properties. However, what if want to place a property next to other properties, which are categorized through a schema-based category? This is now possible through the new SchemaCategory category identifier. For example, to place a calculated property next to an ECProperty that uses MySchema:MyCategory category:
{
"label": "My calculated property",
"categoryId": {
"type": "SchemaCategory",
"categoryName": "MySchema:MyCategory"
}
}Calculated properties specification enhancements
A number of enhancements have been made to calculated properties specification:
- The [
value]($docs/pres...
v4.8.7
Release notes
Changes
- Fix
errormetadata being overwritten in logs (backport #7105) [release/4.8.x] (#7128) - mitigate GHSA-qwcr-r2fm-qrc7 (backport #7146) [release/4.8.x] (#7155)
- Pass includeIncomplete flag to queryGraphicRepresentations (backport #7145) [release/4.8.x] (#7154)
Full changelog: 4.8.6...4.8.7
v4.8.6
v4.8.5
v4.8.4
v4.8.3
v4.8.2
v4.8.1
Release notes
Changes
- Update gather-docs.yaml's branch name to the release branch
- resolve CVE-2022-25883 (backport #7057) [release/4.8.x] (#7059)
- Fix incorrect geometry for black text (backport #7054) [release/4.8.x] (#7056)
- Fix null ref in buildAverageNormals (backport #7063) [release/4.8.x] (#7065)
- Check for the possibility that a TextureId is a number while cloning it. (backport #6933) [release/4.8.x] (#7064)
Full changelog: 4.8.0...4.8.1
v4.8.0
deltaDoc: true
version: '4.8.0'
4.8.0 Change Notes
Table of contents:
- Workspaces
- Electron 31 support
- Type-safe Worker APIs
- Creating graphics in Workers
- Internal APIs
- ListenerType helper
- CustomAttributeClass containerType renamed
- Improve the performance of the ECSchemaRpcLocater
- Mathematical operation parsing
Workspaces
The beta Workspace and Settings APIs have been updated to make them easier to use, including the addition of the WorkspaceEditor API for creating new WorkspaceDbs to hold workspace resources. Consult the learning article for a comprehensive overview with examples.
Electron 31 support
In addition to already supported Electron versions, iTwin.js now supports Electron 31.
Type-safe Worker APIs
The WorkerProxy APIs provide an easy way to leverage Workers in a type-safe way to move processing out of the JavaScript main thread into a background thread.
Creating graphics in Workers
Typically, you would use a GraphicBuilder to create graphics. GraphicBuilder produces a RenderGraphic containing WebGL resources like textures and vertex buffers, so it must execute on the main JavaScript thread. This is fine for simple decorations, but imagine you are streaming large data sets like GeoJSON or point clouds that must be processed into graphics - that would require far more processing which, if executed on the main thread, would utterly degrade the responsiveness of the application by blocking the event loop.
GraphicDescriptionBuilder has been introduced to address this problem. In conjunction with a WorkerProxy, you can move the heavy processing into a background thread to produce a GraphicDescription, leaving to the main thread the fast and straighforward task of converting that description into a RenderGraphic using RenderSystem.createGraphicFromDescription. See this article for an example.
Internal APIs
iTwin.js categorizes the stability of each API using release tags like @public, @beta, and @internal. @internal APIs are intended strictly for use inside of the itwinjs-core repository. They can be tricky to use correctly, and may be changed or removed at any time, so consumers of iTwin.js should not write code that depends on them. Unfortunately, up until now they have been exported from the iTwin.js core packages just like any other type of APIs, making it easy for anyone to accidentally or intentionally introduce a dependency on them. To ensure that we can adhere to our commitment to providing stable libraries, we have begun to transition to a new approach to handling these kinds of APIs.
The details are relevant primarily to contributors, but consumers should expect to find that @internal APIs they currently depend upon have been marked as deprecated. The deprecation messages include information about alternative public APIs to use instead, where appropriate. If you encounter a dependency on an @internal API which you struggle to remove, please let us know. Beginning in iTwin.js 5.0, you will no longer be able to access any @internal APIs.
ListenerType helper
We added a new helper type ListenerType to retrieve the type of the callback function for a given BeEvent. This is useful when implicit types cannot be used - for example, when you need to define a listener outside of a call to BeEvent.addListener.
ecschema-metadata CustomAttributeClass.containerType deprecated and replaced with appliesTo
The Xml and JSON representations of a custom attribute (and related TypeScript interfaces) all use a property named appliesTo of type CustomAttributeContainerType to indicate the kind(s) of schema entities to which the attribute can be applied. Confusingly, the @beta CustomAttributeClass class exposes this same information via a property named containerType. To address this discrepancy, containerType has been deprecated in favor of the new appliesTo property. The protected _containerType property was renamed to _appliesTo.
Improve the performance of the ECSchemaRpcLocater
Improve the performance of the ECSchemaRpcLocater by making all of the underlying ECSchemaRpcInterface methods GET by default so responses are cached by default. Previously each client had to set the methods to be GET or they would default to POST and were not cached.
Mathematical operation parsing
The quantity formatter supports parsing mathematical operations. The operation is solved, formatting every values present, according to the specified format. This makes it possible to process several different units at once.
// Operation containing many units (feet, inches, yards).
const mathematicalOperation = "5 ft + 12 in + 1 yd -1 ft 6 in";
// Asynchronous implementation
const quantityProps = await Parser.parseIntoQuantity(mathematicalOperation, format, unitsProvider);
quantityProps.magnitude // 7.5 (feet)
// Synchronous implementation
const parseResult = Parser.parseToQuantityValue(mathematicalOperation, format, feetConversionSpecs);
parseResult.value // 7.5 (feet)Limitations
Only plus(`+`) and minus(`-`) signs are supported for now. Other operators will end up returning a parsing error or an invalid input result.Usage
The parsing of mathematical operations is disabled by default. To enable it, you can override the default QuantityFormatter. Ex : ```Typescript // App specific const quantityType = QuantityType.LengthEngineering;// Default props for the desired quantityType
const props = IModelApp.quantityFormatter.getFormatPropsByQuantityType(quantityType);
// Override the formatter and enable mathematical operations.
await IModelApp.quantityFormatter.setOverrideFormat(quantityType, { ...props, allowMathematicOperations: true });
v4.7.8
Release notes
Changes
- Presentation: Fix
Presentation.selection.selectionChangeevent not being emitted forBlankConnection(backport #7002) [release/4.7.x] (#7022)
Full changelog: 4.7.7...4.7.8