Documentation - Copilot instructions for OCCT development

.github/copilot-instructions.md

@@ -0,0 +1,247 @@
+# OCCT Copilot Instructions
+
+This file provides the comprehensive guidance for AI assistants working with the Open CASCADE Technology (OCCT) C++17+ 3D CAD/CAM/CAE library.
+
+---
+
+## 1. Core Directives for AI Assistant
+
+> **IMPORTANT:** These are the most critical rules. Follow them strictly.
+
+1.  **Memory Management is Paramount:**
+    - **ALWAYS** use `Handle(ClassName)` for any class inheriting from `Standard_Transient` (e.g., `Geom_*`, `Poly_*`, `AIS_*`, `V3d_*`). This is for reference-counted objects.
+    - **NEVER** use raw pointers (`ClassName*`) for these types, as it will cause memory leaks.
+    - **Correct:** `Handle(Geom_Circle) aCircle = new Geom_Circle(...);`
+    - **Wrong:** `Geom_Circle* aCircle = new Geom_Circle(...);`
+
+2.  **Check Operation Status:**
+    - After using an API that performs a geometric operation (e.g., `BRepAlgoAPI_Fuse`, `BRepBuilderAPI_MakeEdge`), **ALWAYS** check if the operation was successful using the `IsDone()` method before accessing the result.
+    - **Correct:**
+      ```cpp
+      BRepAlgoAPI_Fuse aFuser(theShape1, theShape2);
+      if (aFuser.IsDone()) {
+          auto aResult = aFuser.Shape();
+      } else {
+          // Handle error
+      }
+      ```
+
+3.  **Strict Naming and File Conventions:**
+    - Adhere to the strict `Package_ClassName` convention.
+    - Place new files in the correct directory: `src/Module/Toolkit/Package/`.
+    - After adding a file, **ALWAYS** update the corresponding `src/Module/Toolkit/FILES.cmake` file.
+
+4.  **Use Modern C++ Idioms:**
+    - Prefer `auto` for variable declarations where the type is clear, especially with iterators.
+    - Use range-based `for` loops and structured bindings where applicable.
+    - Use the modern `TopExp_Explorer` constructor style.
+    - **Correct:** `for (TopExp_Explorer anExp(theShape, TopAbs_FACE); anExp.More(); anExp.Next()) { ... }`
+    - **Wrong:** `for (TopExp_Explorer anExp; anExp.Init(theShape, TopAbs_FACE); anExp.More(); anExp.Next()) { ... }`
+
+5.  **Safe Type Casting:**
+    - When downcasting topological shapes, **ALWAYS** use the `TopoDS` helper functions to avoid errors.
+    - **Correct:** `auto aFace = TopoDS::Face(anExp.Current());`
+    - **Wrong:** `auto aFace = (const TopoDS_Face&)anExp.Current();`
+
+6.  **Handle Downcasting:**
+    - Use `Handle(DerivedClass)::DownCast(BaseHandle)` to safely downcast handles.
+    - **Correct:**
+      ```cpp
+      Handle(Geom_Circle) circ = Handle(Geom_Circle)::DownCast(someCurveHandle);
+      ```
+    - **Wrong:**
+      ```cpp
+      // Do not use C-style casts on handles
+      Geom_Circle* circ = (Geom_Circle*)someHandle.Get();
+      ```
+
+7.  **Validate Handles for Null Safety:**
+    - **ALWAYS** check that a `Handle(ClassName)` is not null before dereferencing it:
+      ```cpp
+      if (!theHandle.IsNull()) {
+          // use theHandle
+      }
+      ```
+
+---
+
+## 2. Project Overview
+
+Open CASCADE Technology (OCCT) is a comprehensive C++ software development platform for 3D surface and solid modeling, CAD data exchange, and visualization. It's a modern C++17+ library providing services for CAD/CAM/CAE applications.
+
+### Architecture & Source Organization
+
+- **`src/`**: Source code, organized by a `Module/Toolkit/Package` hierarchy.
+- **`tests/`**: Draw Harness test files, organized by functionality.
+- **`adm/`**: Administrative and build configuration files (CMake).
+- **`samples/`**: Example applications.
+
+---
+
+## 3. Code Conventions
+
+### Naming Patterns
+
+| Element Type                | Pattern                      | Example                          |
+| --------------------------- | ---------------------------- | -------------------------------- |
+| **Classes**                 | `Package_ClassName`          | `TopoDS_Shape`, `BRep_Builder`   |
+| **Public Methods**          | `MethodName`                 | `IsDone()`, `Shape()`            |
+| **Private Methods**         | `methodName`                 | `myInternalMethod()`             |
+| **Method Parameters**       | `theParameterName`           | `theShape`, `theTolerance`       |
+| **Local Variables**         | `aVariableName`              | `aBox`, `anExplorer`             |
+| **Class Member Fields**     | `myFieldName`                | `myShape`, `myIsDone`            |
+| **Struct Member Fields**    | `FieldVariableName`          | `Point`, `Value`                 |
+| **Global Variables**        | `THE_GLOBAL_VARIABLE`        | `THE_DEFAULT_PRECISION`          |
+
+### Type Mappings
+
+| OCCT Type           | C++ Equivalent | Notes                               |
+| ------------------- | -------------- | ----------------------------------- |
+| `Standard_Real`     | `double`       | Use for all floating-point numbers. |
+| `Standard_Integer`  | `int`          | Use for all integer values.         |
+| `Standard_Boolean`  | `bool`         | Use for `true`/`false` values.      |
+
+### Modern C++ Encouraged
+This is a C++17+ codebase. Proactively use modern features to improve code quality:
+- `auto`
+- Range-based `for` loops
+- Structured bindings: `for (const auto& [key, value] : aMap)`
+- `std::optional` for optional return values where appropriate.
+- `if constexpr` for compile-time conditions.
+
+---
+
+## 4. Step-by-Step Workflow Example: Adding a New Class and Test
+
+This example demonstrates the end-to-end process for adding a new class `BRepTest_MyNewClass` to the `TKTopAlgo` toolkit and creating a corresponding GTest.
+
+**1. Create Header and Source Files:**
+Navigate to the correct package directory and create the files.
+```bash
+# Navigate to the BRepTest package in the ModelingAlgorithms module
+cd src/ModelingAlgorithms/TKTopAlgo/BRepTest
+touch BRepTest_MyNewClass.hxx BRepTest_MyNewClass.cxx
+```
+
+**2. Implement the Class:**
+Add content to `BRepTest_MyNewClass.hxx` and `.cxx`, following all code conventions.
+
+**3. Add Files to CMake:**
+Edit the toolkit's `FILES.cmake` to register the new files.
+```bash
+# Edit the CMake file for TKTopAlgo
+vim src/ModelingAlgorithms/TKTopAlgo/FILES.cmake
+```
+Add the new files to the `OCCT_<PackageName>_FILES` list:
+```cmake
+# In FILES.cmake
+...
+set (OCCT_BRepTest_FILES
+    ...
+    BRepTest_MyNewClass.hxx
+    BRepTest_MyNewClass.cxx
+    ...
+)
+```
+
+**4. Create a GTest:**
+Navigate to the GTest directory for the toolkit and create a test file.
+```bash
+# Navigate to the GTest directory for TKTopAlgo
+cd src/ModelingAlgorithms/TKTopAlgo/GTests
+touch BRepTest_MyNewClass_Test.cxx
+```
+Write the test implementation in the new file.
+
+**5. Add GTest to CMake:**
+Edit the same `FILES.cmake` to add the test file.
+```cmake
+# In FILES.cmake
+...
+set (OCCT_TKTopAlgo_GTests_FILES
+    ...
+    GTests/BRepTest_MyNewClass_Test.cxx
+    ...
+)
+```
+
+**6. Build and Run Test:**
+From the `build` directory, build the project and run the tests.
+```bash
+# Navigate to build directory
+cd build
+
+# Re-run CMake to pick up new files (usually not needed, but good practice)
+cmake .. -DBUILD_GTEST=ON
+
+# Build the project
+cmake --build . --config Release
+
+# Run the tests
+./bin/OpenCascadeGTest --gtest_filter=*MyNewClass*
+```
+
+---
+
+## 5. Build and Test System
+
+### Build System (CMake)
+- **Primary build system:** CMake 3.16+ recommended.
+- **Build Directory:** Always build in a separate directory (e.g., `build/`).
+- **Quick Build:**
+  ```bash
+  mkdir -p build && cd build
+  cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_GTEST=ON
+  cmake --build . --config Release --parallel
+  ```
+- **Environment:** Before running any OCCT executable (including tests), you **must** source the environment script: `source build/env.sh` (or `build\env.bat` on Windows).
+
+### Testing Frameworks
+- **Draw Harness:** Tcl-based framework for interactive testing. Located in `tests/`. Run with `build/DRAWEXE`.
+- **GTest:** C++ unit testing framework. Tests are located in `src/.../GTests/`. Enable with `-DBUILD_GTEST=ON`.
+
+---
+
+## 6. Common Patterns & Key Packages
+
+### Common Operations
+
+- **Shape Creation:** Use `BRepPrimAPI_` classes (`MakeBox`, `MakeCylinder`).
+- **Boolean Operations:** Use `BRepAlgoAPI_` classes (`Fuse`, `Cut`, `Common`).
+- **Shape Exploration:** Use `TopExp_Explorer`.
+- **Transformations:** Use `gp_Trsf` and `BRepBuilderAPI_Transform`.
+
+### Key Packages
+
+| Package     | Purpose                               | Module                |
+| ----------- | ------------------------------------- | --------------------- |
+| `gp`        | Geometric Primitives (Points, Vecs)   | FoundationClasses     |
+| `Geom`      | Geometric entities (Curves, Surfaces) | ModelingData          |
+| `TopoDS`    | Topological Data Structures (Shapes)  | ModelingData          |
+| `TopExp`    | Exploring topological shapes          | ModelingData          |
+| `BRepAlgoAPI` | High-level modeling algorithms      | ModelingAlgorithms    |
+| `BRepPrimAPI` | Geometric primitives creation       | ModelingAlgorithms    |
+| `AIS`       | Application Interactive Services      | Visualization         |
+
+### Common Headers
+```cpp
+#include <Standard_Failure.hxx>
+#include <Handle_Geom_Circle.hxx>
+#include <gp_Pnt.hxx>
+#include <gp_Trsf.hxx>
+#include <TopoDS.hxx>
+#include <TopoDS_Face.hxx>
+#include <TopExp_Explorer.hxx>
+#include <BRep_Builder.hxx>
+#include <BRepAlgoAPI_Fuse.hxx>
+#include <BRepBuilderAPI_Transform.hxx>
+#include <BRepPrimAPI_MakeBox.hxx>
+```
+
+---
+
+## 7. Key Files & Platform Notes
+
+- **`adm/MODULES`**: Defines all modules and toolkits.
+- **`src/*/FILES.cmake`**: Lists all source/header files for a toolkit. **You must edit this when adding/removing files.**
+- **`build/env.sh/bat`**: The crucial environment script.

.gitignore

@@ -56,3 +56,18 @@ win64
 /build*
 /install*
 /tools/build*
+
+# Coding agents instructions (keep .github/copilot-instructions.md)
+/.CLAUDE.md
+/.AGENT.md
+/.GEMINI.md
+/.COPILOT.md
+/.CURSOR.md
+/.CODEIUM.md
+/.TABNINE.md
+/.CHATGPT.md
+/.BARD.md
+/.PERPLEXITY.md
+/.CONTINUE.md
+/.AIDER.md
+/.WINDSURF.md