๐๏ธ Migrating previous versions
We deliver new features and bugfixes with each release. While we try to keep the API as stable as possible, there might be situations in which it's impossible to do it without holding back the project progress. That's why we: ๐๐ป
- Keep all the past docs in this page. ๐
- Make a migration guide for each version (starting in 3.1.x) covering all components. ๐
Here you'll learn how to migrate to version 3.1.x from version 3.0.x.
This means migrating from:
โ๐ป Before you startโ
You will need to upgrade all the versions of our libraries, as well as it's peer dependencies (watch out three.js). You can't combine old and new libraries. ๐โก๏ธ๐
This is the legend we'll use to have an easy overview of changes in the API:
- ๐ฐ means no breaking change in the API.
- ใฐ๏ธ means something small changed (e.g. a method/component name changed).
- โฐ means something changed considerably or completely.
- ๐ means the component has been removed temporarily.
- โ๏ธ means the component has been removed permanently.
You'll find more info about removed components below. ๐๐ป
The main purpose of this article is to migrate existing apps, and you can't migrate features that didn't exist before. New features won't be covered here unless they are the substitution of a previous feature. To see how new features work, check out the latest tutorials. The only exception are new features that substitute existing ones, which will be covered here too.
And one last thing: if you get stuck, please ask in our community (ideally, providing a minimal example we can test). ๐ซก
๐ About removed featuresโ
If you have an existing app, it's possible that some of the features you used from previous versions are not there anymore, temporarily or permanently. Depending on the specific scenario, there are different solutions: ๐๐ป
-
โ๏ธ If the feature was permanently removed because it's not needed anymore (e.g. the culler), you shouldn't have a need to replace it. it's not needed anymore (e.g. the culler), so you shouldn't have a need to replace it at all.
-
โ๏ธ If the feature was permanently removed because what it did is done by something else (e.g. the civil tools, which have been merged into one), replacing the component with the new one should give you the features back.
-
โ๏ธ If the feature was permanently removed because we consider it out of scope (like the Json exporter), we append the link to the original code here, so that you can copy and maintain it yourself in your project if you need it.
-
๐ If the feature was temporarily removed because we will add it in a future path or release, you just have to wait until we add it. If you can't wait to have it in your solution, our suggestion is that you stick to the previous version of the library until we add it back.
If you have any questions about your specific case, let us know in the community! ๐ซฑ๐ปโ๐ซฒ๐ป
๐ web-ifcโ
The first thing you will need to do is update web-ifc (our core IFC library) to the correct version. All versions of the library should use the same web-ifc version (let us know otherwise). You can find the correct version here. Please install it as a dependency in your project and use the correct WASM file (tutorials like the IfcLoader cover this). ๐๐ป
๐ fragmentsโ
๐ฐ FragmentsModelsโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. ๐๐ป
๐ฐ IfcImporterโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. ๐๐ป
๐ฐ ModelInformationโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. ๐๐ป
๐ฐ Raycastingโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. ๐๐ป
๐ฐ VisibilityOperationsโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. ๐๐ป
๐ componentsโ
๐ฐ BCFTopicsโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. ๐๐ป
ใฐ๏ธ BoundingBoxerโ
Original tutorial โก๏ธ New tutorial
This API can do pretty much the same as before, but more performantly and with an extra method to give you more control:
-
Before, we generated a three.js mesh that we used to compute the bounding boxes, so you would use add to add the Fragments model, which was a simple three.js mesh (not very performant).
-
Now we are taking advantage of the new Fragments performance and giving you more control. You can use addFromModels if you want to get the bbox of full models (you can select which one by passing an argument with their ids), or addFromModelIdMap if you want the bbox of specific items by defining a model id map as shown in the tutorial. ๐
ใฐ๏ธ Classifierโ
Original tutorial โก๏ธ New tutorial
The classifier can do the same as before and much more, thanks to the performance power of Fragments.
-
Before, it was only possible to classify by entity, relation or model.
-
Now, you can do exactly the same by using the built-in methods to classify. Plus, you can do more things in combination with the finder to create more advanced classifications. Check out the new tutorial for more info about this. ๐ช๐ป
๐ฐ Clipperโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. ๐๐ป
โ๏ธ Cullersโ
Original tutorial โก๏ธ โ๏ธ
The culler's mission was to hide items that were unseen in the scene to increase performance. This problem is already automatically managed by Fragments internally, so there's no need of an external component to do this anymore. โ๐ป
With the new fragments, you should be able to handle bigger models a lot faster than before. If you have any problems or detect any regression, let us know in the community. ๐ซฑ๐ปโ๐ซฒ๐ป
There's no alternative, as this feature wasn't removed per se. It's now automatically managed by Fragments. If you have any issues with this, let us know in the community.
๐ Exploderโ
Original tutorial โก๏ธ ๐
The exploder was a great component to take a look at the model inner spaces like a toy. This had to be removed because the new Fragments don't allow editing (yet). Once we publish the Fragments edit API, we'll put this component back, and this API should be back without changes. ๐ฅ
As an alternative in your application, you can isolate floor plans using the hider. We know, it's not as cool as exploding, but don't worry: this will be back soon.
ใฐ๏ธ FragmentsManagerโ
Original tutorial โก๏ธ New tutorial
Internally, Fragments is now completely different. This has forced us to make 3 changes to this API: ๐งฉ๐งฉ๐งฉ
-
You need to initialize the worker before using Fragments.
-
You need to call
fragments.update()when you want the Fragments models to update their LODs and culling depending on the user's camera position. This is shown in the new tutorial. -
All the fragments related methods are now in
FragmentsManager.core. The reason is that this object is an instance of the FragmentsModels and we don't want to replicate that API. The advantage of using the FragmentsManager is that it's a component, so it's globally available and automatically disposed when callingcomponents.dispose().
๐ฐ Gridsโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. ๐๐ป
๐ฐ Hiderโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. ๐๐ป
โฐ IfcFinderโ
Original tutorial โก๏ธ New tutorial
This component has changed a lot because when we first created it, we did it for IFC STEP. But the very reason why we created Fragments is that we realized that IFC STEP is a format that was never designed to be performant. After years, we could never get a decent 3D viewer with IFC STEP. We didn't want to end up in the same situation with the Finder. ๐ค
All components we create from now on will be using Fragments, our open native format, to take advantage of its performance and speed (except for the IFC STEP importers and exporters of course).
That said, the mission of the finder is the same: find data in our BIM models using complex queries: ๐๐ป
-
Before, the finder allowed to define queries to make text searches directly in the IFC STEP file, with all the performance problems this entails.
-
Now, the finder allow to define the same queries and save them for later with a simpler API that does the same and much better performance.
In summary, you can do the same as before, but the API is different, it works directly in Fragments and it's faster. If you have any problems with this, let us know in the community. ๐ซฑ๐ปโ๐ซฒ๐ป
If in spite of the performance issues you still want to make queries to IFC STEP as we did before, you can take the code of the previous component to your project.
โ๏ธ IfcGeometryTilerโ
Original tutorial โก๏ธ โ๏ธ
The main goal of the IfcGeometryTiler was to set up mesh streaming to be able to represent bigger IFC files. This had various problems: ๐บ
- The set up was very complex and verbose
- It relied too much on the network (slow internet = poor experience)
- The load of bigger objects / many simultaneous was very slow
- It made the logic of many components exponentially more complex and buggy
With the new version of Fragments, this is no longer necessary. Fragments can load hundreds of files or multi gigabytes in seconds without streaming, skipping all the downsides above while keeping the speed benefits. ๐ฅ
There's not alternative because we don't see the need at the moment. As we haven't hit a project we can't open with the new Fragments yet, we have decided to drop streaming for now. We might revisit it in the future if we need to represent thousands of BIM models or hundreds of gigabytes simultaneously.
If you have any performance issues with the new Fragments, let us know in the community.
๐ IfcIsolatorโ
Original tutorial โก๏ธ ๐
The IfcIsolator was created mainly to allow people to send us objects that failed in their IFC files without sending us the whole file, as often they are private. The problem is that its implementation is not very performant, and now we have a new use for this feature. ๐๐ป
Our core IFC library has a limit of ~2gb for IFCs. We want to use the isolator to split down bigger IFC STEP files so that we can process them. And this requires a performant implementation. We are now rebuilding the isolator from scratch. As soon as we have it ready, it will be back with the same API, a much better performance and a key role: allowing us to open gigantic IFC files. ๐ฃ
If you were using the isolator, you can easily copy it's original source code and use it in your project. It's decoupled from anything else. If you have any questions, let us know in the community.
โ๏ธ IfcJsonExporterโ
Original tutorial โก๏ธ โ๏ธ
The main goal of the JSON exporter was to export the properties of the BIM models to JSON, as we had no other way of storing them. This is not very efficient. Now that we have Fragments, our own native format, we don't need this. It's important to note that while exporting an IFC to JSON might sound tempting, IFC STEP is actually less verbose than a JSON, so you will end up with very big files. ๐
If you still want to get a JSON from your IFC STEP files, you can check out the original code, which is very simple and uses our core IFC library.
ใฐ๏ธ IfcLoaderโ
Original tutorial โก๏ธ New tutorial
The API for this just have some slight changes in the signature of the IfcLoader.load method. You can check them out here and here. ๐
๐ IfcPropertiesManagerโ
Original tutorial โก๏ธ โ๏ธ
Editing, creating and deleting properties is key for us, and the only reason we didn't include it here is because we have to rebuild it from scratch for the new Fragments. In the next release (Q3) we are releasing the Fragments Edit API and this component will be back (as well as other components to edit geometries, materials, etc). ๐ฏ
In the meantime, if you want to know how to work with Fragments and properties, you can check out the following tutorials:
โ๏ธ IfcPropertiesTilerโ
Original tutorial โก๏ธ โ๏ธ
The main goal of the IfcPropertiesTiler was to set up mesh streaming to be able to represent bigger IFC files, which is not necessary with the new Fragments. See IfcGeometryTiler for more details. ๐
โ๏ธ IfcRelationsIndexerโ
Original tutorial โก๏ธ โ๏ธ
The main goal of this component was to compute the indirect relations within the IFC STEP file. In IFC, many relations are indirect, so that if you don't preindex them, you are forced to traverse the whole data every time you make a query. That means that in order to know the properties of a wall, you need to traverse the whole IFC (yes, this would be very slow). ๐ฅฒ
Now Fragments does this automatically. All Fragments files relations are indexed. So there's no need for this component anymore. So just like the Cullers, this component was not removed: it's handled by Fragments now. โกโกโก
There's no alternative, as this feature wasn't removed per se. It's now automatically managed by Fragments. If you have any issues with this, let us know in the community.
โ๏ธ MeasurementUtilsโ
Original tutorial โก๏ธ โ๏ธ
The goal of measurement utils was to provide some general logic to create measurements in simple Three.js objects. Now that we have Fragments, we have adapted all the measuring logic to it, and this class is now useless. If you miss any of the specific methods, you can check them out in the old file, as they were not a lot of code. If you want measuring tools check out the alternatives. ๐๐ป
If you want to make measurements in your app, check out the following tutorials: ๐๐
๐ MiniMapโ
Original tutorial โก๏ธ ๐
The only reason this is not available yet is because we didn't have time before the release, but we'll add this back as a patch very soon. In the meantime, let us know in the community if you have any questions. ๐๐ป
๐ฐ OrthoPerspectiveCameraโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. ๐๐ป
ใฐ๏ธ Raycastersโ
Original tutorial โก๏ธ New tutorial
The only change in this component is that now caster.castRay is async because we are also raycasting Fragments, which are managed by web workers and require asynchronous code. โฑ๏ธ
๐ฐ ShadowedSceneโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. ๐๐ป Just make sure you follow the new tutorial to cast shadows on top of the Fragments meshes.
๐ฐ Viewpointsโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. ๐๐ป
๐ฐ Worldsโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. ๐๐ป Make sure to check out the new tutorial, as there are some extra features, and you'll see the combination with the newer components.
๐ components-frontโ
โ๏ธ AngleMeasurementโ
Original tutorial โก๏ธ โ๏ธ
We have removed this component because we haven't seen anyone using it. If you have a need for this, let us know of your use case and we'll add it back! ๐
Tell us about your use case in the community and we'll add it back.
๐ฐ AreaMeasurementโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. Don't forget to check out the latest tutorial to see the new cool features in store.๐๐ป
โฐ Civil3DNavigatorโ
Original tutorial โก๏ธ New tutorial
The previous civil components had several problems: ๐งจ
- They were very disaggregated, making it hard to make them work together in a flexible way.
- They were very opinionated (e.g. it wasn't possible to handle multiple alignments).
So when we rebuild alignments for fragments, given that these components' adoption was still relatively small, we thought it was a great opportunity to improve them. ๐
Now there's a single component: the civil navigators, which allow to do the same you could do with 3d, horizontal and vertical navigator components, but with benefits:
- works with the new Fragments, and therefore it's a lot more performant.
- less opinionated and more flexible (supporting multiple alignments simultaneously).
- supports dynamic station labels.
In the new tutorial, you can see how to create multiple navigators (both 3d and 2d) and combine them with the cross section navigator to have a full civil navigation experience. ๐ฃ๏ธ
๐ฐ CivilCrossSectionNavigatorโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. Don't forget to check out the latest tutorial to see the new cool features in store.๐๐ป
โ๏ธ CivilElevationNavigatorโ
Original tutorial โก๏ธ โ๏ธ
The vertical, horizontal and 3d civil navigators have been merged into one to be able to do the same as before but more flexibly. Check out the civil 3d navigator for more details. ๐ฃ๏ธ
Check out the Civil Navigators tutorial.
โ๏ธ CivilPlanNavigatorโ
Original tutorial โก๏ธ โ๏ธ
The vertical, horizontal and 3d civil navigators have been merged into one to be able to do the same as before but more flexibly. Check out the civil 3d navigator for more details. ๐ฃ๏ธ
Check out the Civil Navigators tutorial.
โฐ ClipEdgesโ
Original tutorial โก๏ธ New tutorial
Due to the integral changes in the structures of the new Fragments, we were force to change the API of the clipping edges, which are tightly coupled with the BIM models geometry. You can do the same as before, but you'll need to make some changes to your code: ๐๐ป
-
โ๏ธ Before, you defined styles to control the appearance of the clipping edges.
-
โ๏ธ Now, you still define styles like before, but you also need to define object and then apply styles to them.
If you have any questions about this, let us know in the community!
ใฐ๏ธ EdgeMeasurementโ
Original tutorial โก๏ธ New tutorial
This component is now just merged with the length measurement component, but it's API is identical. Just check out the tutorial to see how to activate it. ๐
๐ FaceMeasurementโ
Original tutorial โก๏ธ New tutorial
We didn't add this one because we run out of time before the release, but we'll add this as a patch soon. It's going to be part of face measurement, just like edge measurement is a part of length measurement. Likewise, besides the fact that it's now a part of another component, the API won't change. ๐๐ป
๐ฐ Highlighterโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. Don't forget to check out the latest tutorial to see the new cool features in store.๐๐ป
โ๏ธ IfcStreamerโ
Original tutorial โก๏ธ โ๏ธ
The main goal of the IfcPropertiesTiler was to set up mesh streaming to be able to represent bigger IFC files, which is not necessary with the new Fragments. See IfcGeometryTiler for more details. ๐
๐ฐ LengthMeasurementโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. Don't forget to check out the latest tutorial to see the new cool features in store.๐๐ป
๐ฐ Markerโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. Don't forget to check out the latest tutorial to see the new cool features in store.๐๐ป
ใฐ๏ธ Plansโ
Original tutorial โก๏ธ New tutorial
The plans and sections component has been substituted by the more generic and flexible Views component, which is also implemented to work with BCF features. The API is very similar, and here you can see how to create plans as before. To get edges, check out the new clip styler tutorial. ๐
โฐ PostproductionRendererโ
Original tutorial โก๏ธ New tutorial
The old postproduction renderer had some problems:
- ๐ท Added extra dependencies to the project, increasing its size.
- ๐ท It was hard to set up / configure.
- ๐ท The AO effect wasn't very efficient.
- ๐ท The lines and outlines effects visual quality was far from perfect.
With the new postproduction renderer, we have solved this all:
- ๐ธ You can now select styles, which will automatically configure the renderer optimally to have the look you want.
- ๐ธ It doesn't use external libraries, just pure three.js, reducing the dependencies.
- ๐ธ It has an improved lines and outlines effect with better visual quality.
In summary, using the renderer itself won't change much. What changes is how you configure it and fine tune the appearance of your app. If you have any questions, let us know in the community. ๐ซฑ๐ปโ๐ซฒ๐ป
ใฐ๏ธ Sectionsโ
Original tutorial โก๏ธ New tutorial
The plans and sections component has been substituted by the more generic and flexible Views component, which is also implemented to work with BCF features. The API is very similar, and here you can see how to create sections or elevations views as before. To get edges, check out the new clip styler tutorial. ๐
โ๏ธ ShadowDropperโ
Original tutorial โก๏ธ โ๏ธ
The original shadow dropper was made a long time ago to get a performant and beautiful shadow. Now that we have the shadowed scene component (more precise and equally efficient) this doesn't make sense anymore. ๐ถ๏ธ
Use the ShadowedScene instead. If you have any questions or suggestions, let us know in the community!
๐ฐ VolumeMeasurementโ
Original tutorial โก๏ธ โ๏ธ
This API didn't have a breaking change, it's the same in both tutorials. Don't forget to check out the latest tutorial to see the new cool features in store.๐๐ป We removed the tutorial because it's just like the rest of measurement tools. ๐๐
๐ uiโ
๐ฐ Componentโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. Don't forget to check out the latest tutorial to see the new cool features in store.๐๐ป
๐ฐ Tableโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. Don't forget to check out the latest tutorial to see the new cool features in store.๐๐ป
๐ฐ DataTransformโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. Don't forget to check out the latest tutorial to see the new cool features in store.๐๐ป
๐ฐ ExportingDataโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. Don't forget to check out the latest tutorial to see the new cool features in store.๐๐ป
๐ฐ LoadFunctionโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. Don't forget to check out the latest tutorial to see the new cool features in store.๐๐ป
๐ฐ Searchingโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. Don't forget to check out the latest tutorial to see the new cool features in store.๐๐ป
๐ ui-obcโ
โ๏ธ ClassificationsTreeโ
Original tutorial โก๏ธ โ๏ธ
We have removed this one because it can easily be done just using our UI libraries in 3 minutes, so it didn't add much value. You have an example in the classifier tutorial. โ๐ป
Check out the classifier tutorial and build a more powerful menu in 3 minutes.
ใฐ๏ธ ElementPropertiesโ
Original tutorial โก๏ธ New tutorial
We have merged ElementProperties and EntityAttributes in the same component. It covers both use cases and the API changes are minimal. Check out the new tutorial for the new features, and let us know if you have any questions. ๐
ใฐ๏ธ EntityAttributesโ
Original tutorial โก๏ธ New tutorial
We have merged ElementProperties and EntityAttributes in the same component. It covers both use cases and the API changes are minimal. Check out the new tutorial for the new features, and let us know if you have any questions. ๐
๐ฐ ModelsListโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. Don't forget to check out the latest tutorial to see the new cool features in store.๐๐ป
ใฐ๏ธ RelationsTreeโ
Original tutorial โก๏ธ New tutorial
The name of this comonent changed, but it's API is the same. ๐๐ป
๐ฐ TopicsUIโ
Original tutorial โก๏ธ New tutorial
This API didn't have a breaking change, it's the same in both tutorials. Don't forget to check out the latest tutorial to see the new cool features in store.๐๐ป