refactor: update transformation system, improve template readability, and reorganize VTK assembly management

src/Core/Debug.h

@@ -38,6 +38,76 @@
 #include <boost/any.hpp>
 
 
+
+/**
+ * @file Debug.h
+ * @brief Unified Debugging and Monitoring System for uLib.
+ *
+ * # Debug System Documentation
+ *
+ * The `Debug` system provides a flexible, adapter-based mechanism for monitoring
+ * and outputting internal variables and states without hardcoding output logic
+ * into core classes. 
+ *
+ * ## Architecture
+ * 
+ * The system follows an adapter pattern:
+ * 
+ * - **`DebugAdapterInterface`**: The base interface for all output targets. 
+ *   Subclasses define how primitive types and strings are handled (e.g., printing 
+ *   to `std::cout`, writing to a log file, or updating a real-time UI widget).
+ *
+ * - **`Debug` Class**: The central registry. It stores:
+ *   1.  A list of "Adapters" (`DebugAdapterInterface`).
+ *   2.  A list of "Items" to monitor. Each item is a reference to a variable 
+ *       associated with a name.
+ *
+ * - **Type Safety**: Although variables are stored using `boost::any` (type erasure), 
+ *   the system automatically preserves the original type information via 
+ *   internal template adapters (`AnyCastAdapter`), ensuring that the correct 
+ *   overload of the adapter interface is called.
+ *
+ * ## Core Components
+ * 
+ * | Component | Description |
+ * | :--- | :--- |
+ * | `Debug` | The main controller used to add adapters and register variables. |
+ * | `DebugAdapterInterface` | Virtual base for creating new output methods. |
+ * | `DebugAdapterText` | A simple built-in adapter for `std::ostream` output. |
+ *
+ * ## How to Use
+ *
+ * ### 1. Initialize the Debug Object
+ * ```cpp
+ * uLib::Debug dbg;
+ * ```
+ *
+ * ### 2. Add an Adapter
+ * ```cpp
+ * uLib::DebugAdapterText console(std::cout);
+ * dbg.AddAdapter(console);
+ * ```
+ *
+ * ### 3. Register Variables to Monitor
+ * Use the `operator()` to bind a variable by reference.
+ * ```cpp
+ * int frameCount = 0;
+ * std::string state = "Initializing";
+ * dbg("Frames", frameCount);
+ * dbg("Status", state);
+ * ```
+ *
+ * ### 4. Update
+ * Call `Update()` periodically (e.g., once per frame) to push the current 
+ * values of all registered variables to all connected adapters.
+ * ```cpp
+ * while(running) {
+ *    frameCount++;
+ *    dbg.Update(); // This triggers the output
+ * }
+ * ```
+ */
+
 namespace uLib {
 
 
@@ -107,7 +177,6 @@ public:
 
 
 
-
 class Debug {
     typedef detail::DebugAdapterInterface AdapterInterface;
     typedef SmartPointer<detail::DebugAdapterInterface> Adapter;