OCCT/.github/copilot-instructions.md

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:

     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:

     Handle(Geom_Circle) circ = Handle(Geom_Circle)::DownCast(someCurveHandle);
     

   • Wrong:

     // 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:

     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.

# 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.

# Edit the CMake file for TKTopAlgo
vim src/ModelingAlgorithms/TKTopAlgo/FILES.cmake

Add the new files to the OCCT_<PackageName>_FILES list:

# 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.

# 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.

# 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.

# 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:

  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

#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.