OCCT

# OCCT AI Assistant Guidelines

This document provides comprehensive guidance for AI assistants (GitHub Copilot, Claude, ChatGPT, and others) working with the Open CASCADE Technology (OCCT) C++17+ 3D CAD/CAM/CAE library.

---

## 1. Core Directives

> **IMPORTANT:** These are the most critical rules. Follow them strictly.

1.  **Memory Management is Paramount:**
    - **ALWAYS** use `occ::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:** `occ::handle<Geom_Circle> aCircle = new Geom_Circle(...);`
    - **Wrong:** `Geom_Circle* aCircle = new Geom_Circle(...);`
    - **Note:** The legacy `Handle(ClassName)` macro still exists but `occ::handle<>` is preferred in new code.

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())
      {
        const TopoDS_Shape& 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/Package/FILES.cmake` file.

4.  **Use Modern C++ Idioms:**
    - 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:** `const TopoDS_Face& aFace = TopoDS::Face(anExp.Current());`
    - **Wrong:** `const TopoDS_Face& aFace = (const TopoDS_Face&)anExp.Current();`

6.  **Handle Downcasting:**
    - Use `occ::down_cast<DerivedClass>(BaseHandle)` to safely downcast handles.
    - **Correct:**
      ```cpp
      const occ::handle<Geom_Circle> aCircle = occ::down_cast<Geom_Circle>(aCurveHandle);
      // Alternative (legacy): occ::handle<Geom_Circle>::DownCast(aCurveHandle)
      ```
    - **Wrong:**
      ```cpp
      // Do not use C-style casts on handles
      Geom_Circle* aCircle = (Geom_Circle*)aHandle.Get();
      ```

7.  **Validate Handles for Null Safety:**
    - **ALWAYS** check that an `occ::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.
- **`samples/`**: Example applications.

---

## 3. Code Conventions

**NEVER** use non-ASCII symbols in code or comments.

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

### Primitive Types

Use standard C++ primitive types in all code. The old `Standard_*` typedefs are **deprecated** and must not be used:

| Use This        | Instead of (Deprecated)      | Usage                        |
| --------------- | ---------------------------- | ---------------------------- |
| `int`           | ~~Standard_Integer~~         | Integer values               |
| `double`        | ~~Standard_Real~~            | Floating-point numbers       |
| `bool`          | ~~Standard_Boolean~~         | Boolean values               |
| `float`         | ~~Standard_ShortReal~~       | Single-precision floats      |
| `char`          | ~~Standard_Character~~       | Character values             |
| `uint8_t`       | ~~Standard_Byte~~            | Byte values                  |
| `size_t`        | ~~Standard_Size~~            | Size values                  |
| `void*`         | ~~Standard_Address~~         | Generic pointers             |
| `char16_t`      | ~~Standard_ExtCharacter~~    | Unicode characters           |
| `const char*`   | ~~Standard_CString~~         | C-style strings              |
| `true`/`false`  | ~~Standard_True/False~~      | Boolean literals             |

> **WARNING:** All `Standard_*` type aliases in `Standard_TypeDef.hxx` are marked `Standard_DEPRECATED` and will be removed in future versions. Always use native C++ types directly.

### Strings and Collections

**ALWAYS** use OCCT collection classes instead of STL containers:

| OCCT Type                         | Instead of                | Description                |
| --------------------------------- | ------------------------- | -------------------------- |
| `TCollection_AsciiString`         | `std::string`             | ASCII string               |
| `TCollection_ExtendedString`      | `std::wstring`            | Unicode string             |
| `NCollection_Array1<T>`           | `std::vector<T>`          | Fixed-size array (1-based) |
| `NCollection_DynamicArray<T>`           | `std::vector<T>`          | Dynamic array              |
| `NCollection_List<T>`             | `std::list<T>`            | Doubly-linked list         |
| `NCollection_Sequence<T>`         | `std::deque<T>`           | Indexed sequence           |
| `NCollection_Map<K>`              | `std::unordered_set<K>`   | Hash set                   |
| `NCollection_DataMap<K,V>`        | `std::unordered_map<K,V>` | Hash map                   |
| `NCollection_IndexedMap<K>`       | -                         | Indexed hash set           |
| `NCollection_IndexedDataMap<K,V>` | -                         | Indexed hash map           |

> **IMPORTANT: Package-Specific Type Aliases Removed**
>
> Old package-specific type aliases have been **removed** from OCCT. You must use `NCollection_*` templates directly with explicit types:
>
> | Removed Alias (Do Not Use)       | Use Instead                          |
> | -------------------------------- | ------------------------------------ |
> | ~~TColStd_ListOfInteger~~        | `NCollection_List<int>`              |
> | ~~TColStd_Array1OfReal~~         | `NCollection_Array1<double>`         |
> | ~~TColStd_SequenceOfInteger~~    | `NCollection_Sequence<int>`          |
> | ~~TColStd_MapOfInteger~~         | `NCollection_Map<int>`               |
> | ~~TColStd_DataMapOfIntegerReal~~ | `NCollection_DataMap<int, double>`   |
> | ~~TopTools_ListOfShape~~         | `NCollection_List<TopoDS_Shape>`     |
> | ~~TopTools_MapOfShape~~          | `NCollection_Map<TopoDS_Shape>`      |
> | ~~TColgp_Array1OfPnt~~           | `NCollection_Array1<gp_Pnt>`         |
> | ~~TColgp_SequenceOfPnt~~         | `NCollection_Sequence<gp_Pnt>`       |
>
> **Exception:** `TColStd_PackedMapOfInteger` still exists as it has a specialized implementation.

**If STL containers are absolutely necessary**, use OCCT's allocators:

```cpp
#include <NCollection_Allocator.hxx>
#include <NCollection_OccAllocator.hxx>
#include <NCollection_IncAllocator.hxx>

// Option 1: NCollection_Allocator - uses standard OCCT memory allocation
std::vector<gp_Pnt, NCollection_Allocator<gp_Pnt>> aPoints;
std::list<TopoDS_Shape, NCollection_Allocator<TopoDS_Shape>> aShapes;

// Option 2: NCollection_OccAllocator - with custom memory pool (preferred for performance)
occ::handle<NCollection_IncAllocator> anIncAlloc = new NCollection_IncAllocator();
NCollection_OccAllocator<gp_Pnt> anAllocator(anIncAlloc);
std::vector<gp_Pnt, NCollection_OccAllocator<gp_Pnt>> aPooledPoints(anAllocator);
```

### Modern C++ Features

This is a C++17+ codebase. Use modern features where appropriate:
- Range-based `for` loops
- Structured bindings: `for (const auto& [aKey, aValue] : aMap)`
- `std::optional` for optional return values
- `std::variant` for type-safe unions
- `if constexpr` for compile-time conditions
- `[[nodiscard]]`, `[[maybe_unused]]` attributes where appropriate

### Use of `auto` Keyword

Use `auto` **only** in the following cases:
- Where syntax requires it (templates, structured bindings, lambdas)
- To omit the type of object in range-based `for` loops
- To omit the type of container iterators: `auto anIter = aContainer.begin()`

**Avoid** `auto` in these cases:
- To omit long type names (use type aliases instead)
- To omit "obvious" return types
- Simply to avoid typing the actual type

Readability is more important than brevity. Always prefer explicit types.

### Const Correctness

Use `const` for variables that will not be modified after initialization:

```cpp
const double aTolerance = 0.001;
const TopoDS_Shape aShape = aBuilder.Shape();
```

Use `constexpr` for values that can be computed at compile time:

```cpp
constexpr int THE_MAX_ITERATIONS = 100;
constexpr double THE_PI = 3.14159265358979323846;
```

Prefer `const` references to avoid unnecessary copies:

```cpp
void ProcessShape(const TopoDS_Shape& theShape);

for (const TopoDS_Face& aFace : aFaces)
{
  // ...
}
```

---

## 4. Step-by-Step Workflow: Adding a New Class

This example demonstrates adding a new class `BRepLib_MyNewClass` to the `BRepLib` package in the `TKTopAlgo` toolkit.

**1. Create Header and Source Files:**
```bash
cd src/ModelingAlgorithms/TKTopAlgo/BRepLib
touch BRepLib_MyNewClass.hxx BRepLib_MyNewClass.cxx
```

**2. Implement the Class:**
Add content following all code conventions (see sections 3 and 7).

**3. Add Files to Package CMake:**
Edit `src/ModelingAlgorithms/TKTopAlgo/BRepLib/FILES.cmake`:
```cmake
set(OCCT_BRepLib_FILES
  ...
  BRepLib_MyNewClass.hxx
  BRepLib_MyNewClass.cxx
)
```

**4. Create a GTest:**
```bash
cd src/ModelingAlgorithms/TKTopAlgo/GTests
touch BRepLib_MyNewClass_Test.cxx
```

**5. Add GTest to CMake:**
Edit `src/ModelingAlgorithms/TKTopAlgo/GTests/FILES.cmake`:
```cmake
set(OCCT_TKTopAlgo_GTests_FILES
  ...
  BRepLib_MyNewClass_Test.cxx
)
```

**6. Build and Run:**
```bash
cd build
cmake .. -DBUILD_GTEST=ON
cmake --build . --config Release
./bin/OpenCascadeGTest --gtest_filter="*MyNewClass*"
```

---

## 5. Build and Test System

### Build System (CMake)
- **Primary build system:** CMake 3.16+
- **Build Directory:** Always build out-of-source (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 OCCT executables, source the environment:
  - Linux/macOS: `source build/env.sh`
  - Windows: `build\env.bat`

### Testing Frameworks
- **Draw Harness:** Tcl-based interactive testing in `tests/`. Run with `DRAWEXE`.
- **GTest:** C++ unit tests in `src/.../GTests/`. Enable with `-DBUILD_GTEST=ON`.

---

## 6. Common Patterns & Key Packages

### Common Operations

- **Shape Creation:** `BRepPrimAPI_MakeBox`, `BRepPrimAPI_MakeCylinder`
- **Boolean Operations:** `BRepAlgoAPI_Fuse`, `BRepAlgoAPI_Cut`, `BRepAlgoAPI_Common`
- **Shape Exploration:** `TopExp_Explorer`
- **Transformations:** `gp_Trsf` with `BRepBuilderAPI_Transform`

### Key Packages

| Package       | Purpose                               | Module             |
| ------------- | ------------------------------------- | ------------------ |
| `gp`          | Geometric Primitives (Points, Vecs)   | FoundationClasses  |
| `Geom`        | Geometric entities (Curves, Surfaces) | ModelingData       |
| `TopoDS`      | Topological Data Structures           | 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_Handle.hxx>           // occ::handle, occ::down_cast
#include <gp_Pnt.hxx>
#include <gp_Trsf.hxx>
#include <Geom_Circle.hxx>
#include <TopoDS.hxx>
#include <TopoDS_Shape.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>
#include <Standard_Failure.hxx>
#include <NCollection_List.hxx>          // NCollection_List<T>
#include <NCollection_DataMap.hxx>       // NCollection_DataMap<K,V>
#include <NCollection_IndexedDataMap.hxx>// NCollection_IndexedDataMap<K,V>
```

---

## 7. Code Documentation Style

### Header Files (.hxx) - Method Documentation

Use Doxygen-style comments with `//!` prefix:

```cpp
//! Brief description of the method functionality.
//! Additional details if needed.
//! @param[in] theInputParam description of input parameter
//! @param[out] theOutputParam description of output parameter
//! @param[in,out] theInOutParam description of in/out parameter
//! @return description of return value
Standard_EXPORT bool MethodName(const InputType& theInputParam,
                                OutputType&      theOutputParam);
```

**Rules:**
- `@param[in]` for input parameters
- `@param[out]` for output parameters
- `@param[in,out]` for bidirectional parameters
- `@return` for return value description

### Source Files (.cxx) - Method Separators

Each method **MUST** be preceded by:
1. A separator line of exactly 100 characters: `//` followed by 98 `=` signs
2. An empty line after the separator

```cpp
//=================================================================================================

void MyClass::MyMethod(const TopoDS_Shape& theShape)
{
  // Implementation
}

//=================================================================================================

bool MyClass::AnotherMethod()
{
  // Implementation
}
```

**DO NOT use old-style function guards:**
```cpp
// WRONG - Do not use this style:
//=================================================================================================
// purpose: Description of what the method does
// function: MyClass::MyMethod
//=================================================================================================
```

### Technical Comments

Place implementation notes inside the method body:
- At the beginning for overall approach
- Inline where specific logic needs explanation

```cpp
//=================================================================================================

void MyClass::ComplexMethod(const TopoDS_Shape& theShape)
{
  // Using iterative approach for better performance with large shape hierarchies.
  for (TopExp_Explorer anExp(theShape, TopAbs_FACE); anExp.More(); anExp.Next())
  {
    // Handle degenerate faces separately
    const TopoDS_Face& aFace = TopoDS::Face(anExp.Current());
    // ...
  }
}
```

---

## 8. GTest Guidelines

### Test Location and Naming

- Location: `src/Module/Toolkit/GTests/`
- File naming: `ClassName_Test.cxx` or `PackageName_Test.cxx`

### Test Structure

```cpp
#include <gtest/gtest.h>

#include <MyClass.hxx>

// Test fixture (optional)
class MyClassTest : public testing::Test
{
protected:
  void SetUp() override
  {
    // Setup code
  }
};

// Test with fixture
TEST_F(MyClassTest, MethodName_Scenario)
{
  // Arrange
  MyClass anObject;

  // Act
  const bool isSuccess = anObject.SomeMethod();

  // Assert
  EXPECT_TRUE(isSuccess);
}

// Standalone test
TEST(MyClassTest, BasicFunctionality)
{
  // Test implementation
}
```

### Naming Convention

Pattern: `TestFixture.MethodOrFeature_Scenario_ExpectedBehavior`

Examples:
- `DE_WrapperTest.Read_ValidSTEPFile_ReturnsTrue`
- `BRepAlgoAPI_FuseTest.TwoBoxes_ProducesValidShape`
- `gp_PntTest.Distance_SamePoint_ReturnsZero`

### Assertions

- `EXPECT_*` - non-fatal (test continues)
- `ASSERT_*` - fatal (test stops)

Common assertions:
- `EXPECT_TRUE(condition)` / `EXPECT_FALSE(condition)`
- `EXPECT_EQ(actual, expected)` / `EXPECT_NE(actual, expected)`
- `EXPECT_NEAR(actual, expected, tolerance)` - for floating-point
- `EXPECT_THROW(statement, exception_type)` - for exceptions

### Running Tests

```bash
# Build
cmake ..
cmake --build .

# Run all
./bin/OpenCascadeGTest

# Run filtered
./bin/OpenCascadeGTest --gtest_filter="*MyClass*"

# List tests
./bin/OpenCascadeGTest --gtest_list_tests
```

---

## 9. Key Project Files

| File                                        | Purpose                                                |
| ------------------------------------------- | ------------------------------------------------------ |
| `src/MODULES.cmake`                         | Defines all modules                                    |
| `src/Module/TOOLKITS.cmake`                 | Defines toolkits within a module                       |
| `src/Module/Toolkit/PACKAGES.cmake`         | Defines packages within a toolkit                      |
| `src/Module/Toolkit/Package/FILES.cmake`    | Lists source/header files (**edit when adding files**) |
| `src/Module/Toolkit/GTests/FILES.cmake`     | Lists GTest source files                               |
| `src/Module/Toolkit/EXTERNLIB.cmake`        | External library dependencies                          |
| `build/env.sh` / `build/env.bat`            | Environment setup script                               |