Metadata-Version: 2.4
Name: rphelp
Version: 0.1.0
Summary: Pip-installable Python package distributing computer vision experiment text files and algorithms.
Author: RP Help Engineering
License-Expression: MIT
Keywords: computer-vision,image-processing,algorithms,experiments,resources,packaging
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Dynamic: license-file

# rphelp: Packaged Computer Vision Experiment Texts & Algorithms

`rphelp` is a lightweight, reliable, pip-installable Python package that distributes computer vision laboratory experiment implementations, modifiable parameters, and algorithmic reference guides. It allows you to package and distribute these resources so they can be installed on any machine via pip and accessed programmatically or extracted via the command line.

---

## 1. What the Package Contains

The package encapsulates three primary text resource files:

| Filename | Size (bytes) | Lines | Purpose & Contents |
| :--- | :--- | :--- | :--- |
| **`file1.txt`** | 47,634 | 1,419 | Python experiment implementations covering Experiments 1–10 (Image filters, histogram equalization, morphological operations, frequency domain filtering, color segmentation, feature detection, object detection, Kalman filtering). |
| **`file2.txt`** | 22,501 | 872 | Single-image and multi-image parameter configurations and execution scripts utilizing OpenCV and NumPy for computer vision pipelines. |
| **`filealgo.txt`** | 12,573 | 265 | Step-by-step algorithmic specifications, mathematical formulations (SVD, DLT, RANSAC, Bundle Adjustment), and procedural breakdowns across all 10 experiments. |

---

## 2. Requirements

- Python **3.9+** (tested on Python 3.9, 3.10, 3.11, 3.12, 3.13)
- No third-party runtime dependencies required (standard library only).

---

## 3. How to Build the Package

To build the source distribution (`.tar.gz`) and binary wheel (`.whl`), ensure `build` is installed:

### Windows (PowerShell)
```powershell
python -m pip install --upgrade build
python -m build
```

### Linux / macOS (Bash)
```bash
python3 -m pip install --upgrade build
python3 -m build
```

The output archives will be placed in the `dist/` directory:
- `dist/rphelp-0.1.0-py3-none-any.whl` (pure-Python platform-independent wheel)
- `dist/rphelp-0.1.0.tar.gz` (source distribution archive)

---

## 4. How to Install on Another Computer

Transfer the built `.whl` file (`dist/rphelp-0.1.0-py3-none-any.whl`) to the target computer (via USB drive, SCP, network share, etc.), and run:

### Windows (PowerShell / Command Prompt)
```powershell
python -m pip install rphelp-0.1.0-py3-none-any.whl
```

### Linux / macOS (Bash)
```bash
python3 -m pip install rphelp-0.1.0-py3-none-any.whl
```

Pip will install the package directly into the active Python environment or virtual environment. All three `.txt` files are bundled inside the installed package.

---

## 5. Python Resource Access API

After installing `rphelp`, you can access the files from any Python script using the public API:

```python
from rphelp import list_files, read_text, read_bytes, copy_files

# 1. List all packaged resource files
files = list_files()
print("Packaged files:", files)
# Output: ['file1.txt', 'file2.txt', 'filealgo.txt']

# 2. Read the full text of a specific file
content = read_text("filealgo.txt")
print(content[:200])

# 3. Read binary contents (preserving raw bytes)
raw_data = read_bytes("file1.txt")
print(f"Read {len(raw_data)} bytes")

# 4. Extract all three files into a destination directory
copied_paths = copy_files("./downloaded_text_files", overwrite=False)
for path in copied_paths:
    print(f"Copied to: {path}")
```

### API Function Reference

- **`list_files() -> list[str]`**  
  Returns the list of names of all bundled text files (`['file1.txt', 'file2.txt', 'filealgo.txt']`).

- **`read_text(filename: str, encoding: str = "utf-8") -> str`**  
  Reads and returns the contents of the given packaged text file as a string.  
  - Validates against path traversal attempts (`..`, `/`, `\`) and raises `ValueError`.  
  - Raises `FileNotFoundError` if the filename is not one of the packaged resources.

- **`read_bytes(filename: str) -> bytes`**  
  Reads and returns raw binary bytes of the requested resource.

- **`copy_files(destination: str | Path, overwrite: bool = False) -> list[Path]`**  
  Extracts all three text files into `destination`.  
  - Creates the destination directory automatically if it does not exist.  
  - If any target file already exists in `destination` and `overwrite=False`, raises `FileExistsError` to prevent accidental data loss.  
  - Set `overwrite=True` to explicitly overwrite existing destination files.

---

## 6. Command-Line Interface (CLI)

The package provides two CLI commands registered in `[project.scripts]`: `rphelp` and `rphelp-files`.

### Extracting Files
To extract all three files into a folder:

#### Windows (PowerShell)
```powershell
rphelp extract --output ./downloaded_text_files
```

#### Linux / macOS (Bash)
```bash
rphelp extract --output ./downloaded_text_files
```

If the destination files already exist, pass `--overwrite` (or `-f`):
```bash
rphelp extract --output ./downloaded_text_files --overwrite
```

### Listing Bundled Files
```bash
rphelp list
```
Output:
```text
Packaged text files (3):
  - file1.txt
  - file2.txt
  - filealgo.txt
```

### Viewing a File in the Terminal
```bash
rphelp show filealgo.txt
```

### Command Help & Version
```bash
rphelp --help
rphelp --version
```

---

## 7. Installing from Git Repository (Optional)

If this repository is hosted on GitHub or another Git remote:

```bash
python -m pip install git+https://github.com/your-username/rphelp.git
```

Or for a specific release tag:
```bash
python -m pip install git+https://github.com/your-username/rphelp.git@v0.1.0
```

---

## 8. Publishing to PyPI (Optional Public Distribution)

To publish the package to PyPI (Python Package Index):

> [!IMPORTANT]
> Never publish credentials or run upload commands without verifying PyPI tokens. Do not publish without explicit permission.

1. Install `twine`:
   ```bash
   python -m pip install --upgrade twine
   ```

2. Check the distribution archives for packaging errors:
   ```bash
   python -m twine check dist/*
   ```

3. (Recommended) Test uploading to TestPyPI first:
   ```bash
   python -m twine upload --repository testpypi dist/*
   ```
   Verify installation from TestPyPI:
   ```bash
   python -m pip install --index-url https://test.pypi.org/simple/ --no-deps rphelp
   ```

4. Upload to official PyPI:
   ```bash
   python -m twine upload dist/*
   ```

5. Once uploaded, anyone can install via pip:
   ```bash
   python -m pip install rphelp
   ```

---

## 9. Updating the Package Version

When updating the package or adding new files:

1. Update the version string in `pyproject.toml`:
   ```toml
   [project]
   version = "0.2.0"
   ```
2. Update `__version__` in `src/rphelp/__init__.py`:
   ```python
   __version__ = "0.2.0"
   ```
3. Re-build the distributions:
   ```bash
   python -m build
   ```
4. Test and install the newly generated wheel `dist/rphelp-0.2.0-py3-none-any.whl`.

---

## 10. Project Structure

```text
rphelp/
├── .gitignore
├── LICENSE
├── MANIFEST.in
├── pyproject.toml
├── README.md
├── file1.txt                     <-- Original text file
├── file2.txt                     <-- Original text file
├── filealgo.txt                  <-- Original text file
├── src/
│   └── rphelp/
│       ├── __init__.py           <-- Package entry point
│       ├── cli.py                <-- Command-line interface
│       ├── file1.txt             <-- Bundled resource file
│       ├── file2.txt             <-- Bundled resource file
│       ├── filealgo.txt          <-- Bundled resource file
│       ├── py.typed              <-- Typing marker
│       └── resources.py          <-- Resource access API
└── tests/
    └── test_resources.py         <-- Comprehensive test suite
```

---

## 11. License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
