Metadata-Version: 2.4
Name: cos-comparison
Version: 0.2.0
Summary: Local similarity comparison for feature extraction – biologically inspired, zero‑training edge/pattern detection, now with cognitive architecture layers.
Author-email: Li Jinxin <your-email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/cos-comparison
Project-URL: Repository, https://github.com/yourusername/cos-comparison.git
Project-URL: Documentation, https://cos-comparison.readthedocs.io/
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: numpy
Requires-Dist: numpy>=1.20; extra == "numpy"
Provides-Extra: c-backend
Dynamic: license-file

# Cos Comparison

[![PyPI version](https://badge.fury.io/py/cos-comparison.svg)](https://pypi.org/project/cos-comparison/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Local similarity comparison for feature extraction – biologically inspired, zero‑training edge / pattern detection.**

---

## Core Idea

Information is produced by **local comparison** in raw data.  
This module implements the **centre‑surround antagonism** mechanism from neuroscience, extracting edges, textures, and keypoints using only sliding window similarity.

The main formula (cosine‑modulated similarity):

\[
\text{cosmod} = \frac{2\,(A\cdot B)}{\|A\|^2 + \|B\|^2}
\]

- **Spurt for real AGI**
- **No training, no labels, no backpropagation**
- Works on **1D, 2D, 3D, 4D** data (audio, images, video, volumes)
- Supports **passive** (reflex) and **active** (template matching) modes
- Pure Python core + optional **NumPy / C acceleration**

---

## Core Principles

1. **Information is generated by local comparison** – edges, textures, patterns arise from comparing neighbouring regions.
2. **Centre‑surround antagonism** – two sliding windows compared with a fixed displacement vector `d`, mimicking retinal ganglion cells.
3. **Three complementary similarity measures** – `_cos` (angular), `_mod` (magnitude), `_cosmod` (recommended combination).
4. **Dual operational modes** – **passive** (detects boundaries without templates) and **active** (template matching with user‑supplied kernel).
5. **Multi‑scale and multi‑directionality** – vary window size for scale, change `d` for orientation selectivity (vertical, horizontal, diagonal).
6. **Dimension‑agnostic** – same algorithm works on 1D, 2D, 3D, 4D and beyond.
7. **Zero training, zero labels** – deterministic computation, ready to use.
8. **Full determinism and interpretability** – every output has a clear geometric meaning.
9. **Modular, pluggable architecture** – pure Python reference, NumPy vectorised, C high‑performance backends with automatic fallback.

---

## ⚠️ Important Note for Version 0.2.0

Starting from version **0.2.0**, the package has been restructured.  
All core functions are now located in the `core` submodule.

**To use the library, please import from `cos_comparison.core`:**

```python
from cos_comparison import core as cc
```

Old code using `import cos_comparison as cc` will **not** work with 0.2.0.  
Update your imports accordingly.

---

## Installation

```bash
pip install cos-comparison
```

To install with NumPy acceleration:
```bash
pip install cos-comparison[numpy]
```

---

## Quick Start

### 1D – find similar segments (passive mode)
```python
from cos_comparison import core as cc

data = [1.0, 2.0, 3.0, 4.0, 5.0]
result = cc.cos_comparison_passive_1d(
    data,
    window_size=(2,),
    step=(1,),
    d=(1,)
)
print(result)
```

### 2D – edge detection (passive mode)
```python
image = [
    [1, 1, 0, 0],
    [1, 1, 0, 0],
    [0, 0, 1, 1],
    [0, 0, 1, 1]
]
edges = cc.cos_comparison_passive_2d(
    image,
    window_size=(2, 2),
    step=(1, 1),
    d=(1, 0)
)
print(edges)
```

### Active mode – template matching
```python
data = [1.0, 2.0, 3.0, 4.0, 5.0]
kernel = [1.0, 0.0]
result = cc.cos_comparison_active_1d(
    data,
    kernel=kernel,
    step=(1,)
)
print(result)
```

### Whole‑tensor cosine
```python
a = [1, 2, 3]
b = [2, 3, 4]
sim = cc.cos_1d(a, b)
print(sim)
```

### Using the recommended `_cosmod` similarity
```python
result = cc.cos_comparison_passive_1d(
    data,
    window_size=(2,),
    step=(1,),
    d=(1,),
    algorithm=cc._cosmod
)
```

---

## Optional Backends

The package automatically selects the fastest available backend:

| Priority | Backend      | Requirement                                      |
|:---------|:-------------|:-------------------------------------------------|
| 1        | C            | Compile `cos_comparison_c/include/core.c`        |
| 2        | NumPy        | `pip install numpy`                              |
| 3        | Pure Python  | Works out of the box                             |

You can force a specific backend via environment variable:
```bash
export COS_BACKEND=cos_comparison.core,cos_comparison_numpy
```

---

## API Overview

### Passive mode (self‑similarity)
- `cos_comparison_passive_1d` / `_2d` / `_3d` / `_4d` + generic N‑dim `cos_comparison_passive`

### Active mode (template matching)
- `cos_comparison_active_1d` / `_2d` / `_3d` / `_4d` + generic N‑dim `cos_comparison_active`

### Whole‑tensor cosine
- `cos_1d` / `_2d` / `_3d` / `_4d`

### Statistics (sliding window)
- `mean_local_1d` / `_2d` / `_3d` / `_4d`
- `local_variance_1d` / `_2d` / `_3d` / `_4d`

### Generic helpers
- `cos(A, B, algorithm=cc._cos)` – works on arbitrarily nested lists
- `execute_many(func, arg_iter, kwarg_iter)` – batch execution (returns list)
- `execute_many_iter(func, arg_iter, kwarg_iter)` – batch execution (generator)

---

## Command Line Interface

```bash
python -m cos_comparison.core passive --data input.json --window 3 3 --output out.json
```

---

## License

MIT © 2025 Li Jinxin. See [LICENSE](https://pypi.org/project/cos-comparison/) for details.

##Other

I born in May 31 2008,and I am still a student.
Because I have to perpare for a very important examination,I decide that I will not maintain the module untill June 9 2026.
