# Sense Core (s6)

Sense Core (package `s6`) is a modular framework for real-time multi-camera instrument tracking, 3D reconstruction, and robotic control. It provides tools for camera calibration, data streaming, inference pipelines, visualization, and hardware integration.

## Features
- Real-time detection and 3D triangulation of instrument tip points using multiple cameras
- Interactive GUI (Vispy + PyQt6) displaying live feeds, synthesized views, 3D frustums, and trajectories
- Robotic control interface for XYZ motion and lighting adjustments via RPC or manual keyboard input
- Video stream server based on FastAPI for remote camera feed access
- Blender-based rendering pipeline for synthetic view generation
- Offline dataset preview and annotation visualization tools
- Built-in profiling and performance statistics export
- Command-line interface for launching individual components

## Installation
1. Clone the repository:
   ```bash
   git clone <repo-url>
   cd <repo-directory>
   ```
2. (Optional) Create and activate a Python virtual environment:
   ```bash
   python3 -m venv venv
   source venv/bin/activate
   ```
3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```
4. (Optional) Install the package in editable mode:
   ```bash
   pip install -e .
   ```

## Quick Start
Use the `s6` CLI to launch modules:
```bash
s6 <module> [options]
```
Alternatively, invoke via Python:
```bash
python -m s6.app.main <module> [options]
```

To extend the CLI with new commands or nested subcommands, simply add new Python modules or subdirectories under `src/s6/app`. Each module should define a `main()` function as the entrypoint. For example, placing `src/s6/app/tools/foo.py` with a `main()` allows invoking:
```bash
s6 tools foo [options]
```


## Remote Operations

The `s6` package supports remote servo control and snapshot capture via RPC and HTTP streaming.

#### Loading Connection Configuration

```python
from s6.schema.connection import ConnectionConfig

# Load the remote stream server address from a JSON config file
config = ConnectionConfig.parse_file("configs/common.config.json")
```

## Unit Testing

This section outlines best practices for designing and writing unit tests in the `s6` project, as well as instructions for running the test suite.

### Test Design Guidelines

- File and Naming Conventions
  - Name test files with `test_*.py`.
  - Place test files alongside the code they test, mirroring the source directory structure.
  - Define test classes inheriting from `unittest.TestCase` or use pytest-style functions when pytest is available.
  - Prefix test methods or functions with `test_` to ensure automatic discovery.

- Test Structure and Scope
  - Write small, focused tests that verify a single behavior or function.
  - Use `setUp`/`tearDown` (unittest) or pytest fixtures for setup and cleanup.
  - Mock external dependencies (I/O, network, hardware) with `unittest.mock` or pytest's `monkeypatch`.
  - Keep tests independent and deterministic; avoid reliance on shared state or random data without fixed seeds.

- Assertions and Feedback
  - Use clear assertion methods (`assertEqual`, `assertTrue`, `assertRaises`, etc.) or pytest assertions.
  - Include informative messages for expected vs. actual results when necessary.

- Performance and Scope
  - Aim for fast execution; avoid long-running or resource-intensive operations in unit tests.
  - Separate integration or end-to-end tests (if any) from unit tests.

- Test Coverage
  - Strive for high coverage on core modules (e.g., vision, datastore, profiler, networking).
  - Use coverage tools (e.g., pytest-cov) to identify untested code paths.

### Running Tests

1. Install dependencies:

   ```bash
   pip install -r requirements.txt
   pip install -e .[dev]     # includes pytest and other dev tools
   ```

2. Run the full test suite via the s6 CLI (uses unittest):

   ```bash
   s6 test
   ```

3. Alternatively, run tests directly with unittest:

   ```bash
   python -m unittest discover -s src/s6 -p "test_*.py"
   ```

4. If pytest is installed, you can use it for more features:

   ```bash
   pytest
   pytest --maxfail=1 --disable-warnings -q
   ```

5. To generate a coverage report (requires pytest-cov):

   ```bash
   pytest --cov=src/s6 --cov-report=term-missing
   ```
## Profiler

The `Profiler` class (in `s6.utils`) provides fine-grained performance tracing within pipelines and applications.

- `Profiler.frame()`: Context manager for timing overall frame or iteration processing.
- `Profiler.trace(scope_name: str, remark: str = None)`: Context manager for named code regions.
  * `scope_name` must follow snake_case naming convention (lowercase letters, numbers, and underscores).
- `trace.attach(**kwargs)`: Attach custom metadata (e.g., coordinates, counters) to the current trace.

Example:
```python
from s6.utils import Profiler

with Profiler.frame():
    with Profiler.trace("array_copy", remark="convert rgb to grayscale") as trace:
        # perform array operations
        trace.attach(size=len(data))
```

The profiler writes detailed timing data and metadata to `frames.log.jsonl` alongside datasets or logs.