chore: improve example descriptions

Author: HoyosJuan

packages/core/src/core/Clipper/example.ts

@@ -1,13 +1,9 @@
 /* MD
   ## ✂️ Cutting Models
   ---
-  The Clipping Tool is a powerful feature in 3D modelling that helps you dissect 3D objects. Clipping Tool is useful for inspecting and analyzing objects in detail.💪
+  Inspecting the interior of a BIM model — checking wall thicknesses, MEP routing, or structural connections — is impossible when geometry blocks the view. Clipping planes solve this by cutting through the model along any surface, revealing exactly what's inside.
 
-  :::tip Clipping?
-
-  Clipping is the process of "cutting" a 3D object by creating a plane. That way, we can have a bird view of the inside of a BIM model.
-
-  :::
+  This tutorial covers creating clipping planes on double click, deleting them individually or all at once, toggling them on and off, and customizing their color, opacity and size. By the end, you'll have a fully working clipping tool ready to drop into any BIM application.
 
   ### 🖖 Importing our Libraries
   First things first, let's install all necessary dependencies to make this example work:

packages/core/src/core/Grids/example.ts

@@ -1,13 +1,9 @@
 /* MD
   ## 📄 Adding Fancy Grids
   ---
-  In this tutorial you'll learn how to add a fancy grid to your scene. It's super easy and will make your app look much more professional!
+  Without a spatial reference, users navigating an empty or partially loaded 3D scene have no sense of scale or orientation. An infinite grid provides that grounding — a neutral plane that adapts to the model's coordinate system and stays out of the way.
 
-  :::tip Why a grid?
-
-  Grids are very common in 3D apps, and it's a great way to have a reference point for your users to navigate around, even when there are no visible objects around.
-
-  :::
+  This tutorial covers creating a grid for a world, snapping it to a specific building storey elevation read directly from the model, and controlling its visibility, color, and primary and secondary cell sizes through a UI panel. By the end, you'll have a configurable grid ready to orient your users in any BIM scene.
 
   ### 🖖 Importing our Libraries
   First things first, let's install all necessary dependencies to make this example work:

packages/core/src/core/OrthoPerspectiveCamera/example.ts

@@ -1,13 +1,9 @@
 /* MD
   ## 📄 Handling Fancy Cameras
   ---
-  Sometimes, you need perspective for depth and realism. Other times, you need an orthographic camera to get precise measurements and proportions. Luckily for you, we have a camera that has both of those projections at the same time! It also has some cool functionality for navigation. In this tutorial, you'll learn to use it. 
+  BIM applications need two navigation modes: perspective for exploring the 3D model naturally, and orthographic for reading plans and sections with accurate proportions. Switching between them mid-session — without losing the camera position — is what the `OrthoPerspectiveCamera` is built for.
 
-  :::tip Orthographic and Perspective cameras
-
-  The difference between Orthographic and Perspective cameras is that Orthographic cameras don't see things smaller when they are further away. This has some implications, like the camera being always "outside" of your scene. You can't see the interior of a room with an orthographic camera. The most common use for orthographic cameras are 2D floor plans and sections, but they can also be used to create cool-looking 3D scenes.
-
-  :::
+  This tutorial covers switching between perspective and orthographic projections, changing navigation modes (Orbit, First Person, and Plan), locking user input, and fitting the camera to the loaded model. By the end, you'll have a fully controllable camera ready for both 3D exploration and 2D plan navigation.
 
   ### 🖖 Importing our Libraries
   First things first, let's install all necessary dependencies to make this example work:

packages/core/src/core/Raycasters/example.ts

@@ -1,7 +1,9 @@
 /* MD
   ## 📄 Picking With the Mouse
   ---
-  Ray casting is the process of casting a ray from a point in space to another point in space. We will cast a ray from the mouse position to the 3D world and check if there is an object in its way. That way, when you hover or click on an object, we can know which one it is and do something with it. In this tutorial you'll learn how to use the Raycaster to pick objects in the scene with the mouse.
+  Knowing which element the user is pointing at is the foundation of almost every interaction in a BIM app — selecting, highlighting, inspecting, placing tools. Without it, clicks and hovers have no context. The Raycaster bridges the mouse position and the 3D scene, identifying exactly which model element is underneath the cursor.
+
+  This tutorial covers casting a ray on double click, resolving the hit to a specific model element, changing its color, and displaying its name in a UI panel. By the end, you'll have a working element picker that you can build any selection-driven feature on top of.
 
   ### 🖖 Importing our Libraries
   First things first, let's install all necessary dependencies to make this example work:

packages/core/src/core/ShadowedScene/example.ts

@@ -2,20 +2,9 @@
 ### 🚀 Handling BIM models like a boss
 ---
 
-In this tutorial, you'll learn how to load your BIM models in Fragment format. Fragment is an [open source geometry system](https://github.com/ThatOpen/engine_fragment/) that we created on top of [Three.js](https://threejs.org/) to display BIM models fast, while keeping control over the individual items of the model. The idea is simple: a BIM model is a FragmentsGroup, which is (like the name implies) a collection of fragments. A fragment is a set of identical geometries instantiated around the scene.
+Flat-lit 3D scenes feel disconnected and hard to read — without shadows, users lose depth cues and the model looks like a technical diagram rather than a real building. The `ShadowedScene` adds ground shadows that follow the model geometry, making the scene immediately more readable and visually grounded.
 
-:::tip How do I get a BIM model in Fragment format?
-
-The IfcLoader component does exactly that! It converts IFC models to Fragments. Check out that tutorial if you are starting out with IFC files. Of course, you can just use the IfcLoader in your app, but loading fragments is more than x10 faster than loading IFC files. Our recommendation is to convert your IFC files to fragments just once, store the fragment somewhere (frontent of backend) and then load the fragments instead of teh IFC models directly.
-
-:::
-
-In this tutorial, we will import:
-
-- `Three.js` to get some 3D entities for our app.
-- `@thatopen/ui` to add some simple and cool UI menus.
-- `@thatopen/components` to set up the barebone of our app.
-- `Stats.js` (optional) to measure the performance of our app.
+This tutorial covers setting up a `ShadowedScene` in place of the standard scene, configuring shadow cascade and resolution, enabling cast and receive shadows per mesh, and toggling shadows on and off at runtime. By the end, you'll have a BIM scene with live shadows that update as the camera comes to rest.
 */
 
 import * as THREE from "three";

packages/core/src/core/Viewpoints/example.ts

@@ -1,15 +1,9 @@
 /* MD
   ## 📄 Storing View Information
   ---
-  Most 3D applications commonly store camera positions for easy retrieval. In BIM apps, it's also useful to store selected and filtered elements. While there isn't a universal standard for this, the BCF schema (used for communication between BIM apps) includes topics and viewpoints.
+  In collaborative BIM workflows, teams need to point each other to specific locations in the model — a clashing duct, a problematic wall, a structural element to review. Without a standard way to save and restore camera positions alongside element selections, that context is lost between sessions and tools. Viewpoints, part of the BCF standard, solve this by bundling camera position, selected elements, and a snapshot into a single reusable reference.
 
-  :::info
-
-  Topics store communication details like title, type, status, assignee, and comments. Viewpoints define camera positions, targets, selected elements, and isolations.
-
-  :::
-
-  The Viewpoints component in That Open Engine extracts BCF viewpoints, enabling you to manage camera positions and related elements effectively. Let's explore how to use it!
+  This tutorial covers creating a viewpoint from the current camera, updating its snapshot and position, associating model elements by GUID and by category query, restoring the camera from a saved viewpoint, isolating its elements in the scene, and linking it to a BCF topic. By the end, you'll have a complete viewpoint workflow ready to integrate into any BIM coordination feature.
 */
 
 import * as THREE from "three";

packages/core/src/core/Views/example.ts

@@ -1,7 +1,9 @@
 /* MD
 ## 📄 Adding 2D Views
 ---
-  In the construction industry, 2D views such as plans, elevations, and sections are essential for understanding and communicating project details effectively. With That Open Engine, you can create and manage these views seamlessly, leveraging its powerful and efficient handling of BIM data to streamline workflows and enhance visualization. Let's see how is done!
+  Reviewing a BIM model in 3D is great for spatial understanding, but design communication still relies on 2D — floor plans to check room layouts, elevations to read façade heights, sections to inspect wall and slab assemblies. Switching to these views manually is tedious; generating them programmatically from the model data is the right approach.
+
+  This tutorial covers generating floor plan views automatically from IFC storeys, creating elevation views from the model's bounding box, and placing arbitrary section views interactively with a double click on any surface. By the end, you'll have a fully working 2D views system with plans, elevations, and on-demand sections navigable from a UI panel.
   
   ### 🖖 Importing our Libraries
   First things first, let's install all necessary dependencies to make this example work:

packages/core/src/core/Worlds/example.ts

@@ -3,20 +3,9 @@
 ### 🌎 Creating our 3D world
 ---
 
-In this tutorial you'll learn how to create a simple scene using `@thatopen/components`.
+Every BIM application needs a 3D environment to display models — a scene, a camera, and a renderer wired together and running. Setting this up from scratch with raw Three.js requires boilerplate that distracts from the actual app logic. The `Worlds` component gives you that foundation in a few lines, with sensible defaults and singleton management built in.
 
-:::tip Hello world!
-
-A world represents a 3D environment in your application. It consists of a scene, a camera and (optionally) a renderer. You can create multiple worlds and show them in multiple viewports at the same time.
-
-:::
-
-In this tutorial, we will import:
-
-- `Three.js` to get some 3D entities for our app.
-- `@thatopen/components` to set up the barebone of our app.
-- `@thatopen/ui` to add some simple and cool UI menus.
-- `Stats.js` (optional) to measure the performance of our app.
+This tutorial covers creating a world with a scene, camera, and renderer, loading a BIM model into it, and controlling background color and light intensities through a UI panel. By the end, you'll have the minimal working scene that every other tutorial in the library builds on.
 
 */
 

packages/core/src/drawings/TechnicalDrawings/example.ts

@@ -1,12 +1,9 @@
 /* MD
   ## 📐 Technical Drawings
   ---
-  Technical drawings are 2D annotations anchored in 3D space, used in architecture,
-  engineering, and construction to communicate design intent precisely. In That Open
-  Engine, a drawing is a container you place anywhere in your 3D scene — move it,
-  rotate it, or scale it and everything inside follows. Annotation systems plug into
-  it, and all data can be exported to DXF for use in any CAD application. Let's see
-  how it works!
+  BIM models communicate design intent in 3D, but construction documentation still relies on 2D drawings with precise annotations — wall lengths, clearances, structural spans. Adding those annotations manually to a screenshot loses the connection to the model data and can't be exported to CAD. Technical drawings solve this by anchoring 2D annotation geometry directly in 3D space, on top of projection lines derived from the model, and exporting everything to DXF.
+
+  This tutorial covers creating a drawing container in the 3D scene, loading projection lines from a model, registering a linear dimensions system, placing dimensions interactively by clicking projection line segments, rendering text labels on commit, and exporting the result to DXF. By the end, you'll understand the core architecture of the technical drawing system that all the other drawing tutorials build on.
 
   ### 🖖 Importing our Libraries
   First, let's install all necessary dependencies to make this example work:

packages/core/src/drawings/TechnicalDrawings/examples/AnnotationStyles/example.ts

@@ -1,11 +1,9 @@
 /* MD
   ## 🎨 Annotation Styles
   ---
-  Every annotation system in That Open Engine renders its geometry using a named
-  style. A style is a plain object that controls colours, line sizes, text
-  properties — and, most importantly, the **tick mark** at the endpoints of a
-  dimension. In this tutorial we'll register styles using the built-in tick
-  builders, then write a custom mesh builder and register a fully custom style.
+  Dimensions that all look the same make drawings harder to read — architects, structural engineers, and MEP teams each have their own visual conventions for tick marks, colors, and units. Annotation styles let you define those conventions once by name and apply them consistently across every dimension in the drawing.
+
+  This tutorial covers registering named styles using all built-in line and mesh tick builders, implementing a fully custom mesh tick builder from scratch, setting per-style measurement units, and switching styles live from a UI dropdown. By the end, you'll have a catalogue of dimension styles — including a custom one — ready to apply to any annotation system.
 
   ### 🖖 Importing our Libraries
   First, let's install all necessary dependencies to make this example work: