Jcy-utils 0.0.3
A collection of image processing utilities for splitting, concatenation, and metrics calculation.
Requires Python: >=3.7

# Jcy_utils

A comprehensive Python utility library for image processing, file management, and metric calculations.

## 📦 Installation

```bash
pip install Jcy_utils
```

## 🚀 Features

- **Image Manipulation**: Split images, add text, pad to square, resize proportionally, and concatenate images.
- **Batch Processing**: Recursively process directories with progress bars.
- **Metrics**: Calculate Precision, Recall, TP, FP, etc., for classification tasks.
- **Utilities**: Retry decorators, file copying tools.

## 📖 Usage Examples

### 1. Add Text to Image
```python
from Jcy_utils import add_text_to_image

add_text_to_image(
    input_path="input.jpg",
    output_path="output.jpg",
    text="Sample Text",
    position=(50, 50),
    color=(255, 0, 0) # Red
)
```

### 2. Concatenate Images
Combine multiple images into a grid layout automatically.

```python
from Jcy_utils import concat_images_list_with_padding_rowmax

images = ["img1.jpg", "img2.jpg", "img3.jpg", "img4.jpg"]
concat_images_list_with_padding_rowmax(
    images, 
    target_size=512, 
    save_path="grid_result.jpg", 
    max_images_per_row=2
)
```

### 3. Batch Directory Processing
Apply a custom function to every image in a folder structure.

```python
from Jcy_utils import wrap_dir

def my_process(input_path, output_path):
    # Your custom logic here
    pass

wrap_dir(
    func=my_process,
    in_dir="./data/source",
    out_dir="./data/processed",
    ext=['jpg', 'png'],
    level=0  # 0 means auto-detect depth
)
```

### 4. Calculate Metrics
Compute Precision/Recall by comparing Ground Truth (GT) and Prediction dictionaries.

```python
from Jcy_utils import calculate_pr2

gt = {'img1': 1, 'img2': 0, 'img3': 1}
pred = {'img1': 1, 'img2': 1, 'img3': 0}

metrics = calculate_pr2(gt, pred)
print(f"Precision: {metrics['precision']:.2f}, Recall: {metrics['recall']:.2f}")
```

### 5. Resize Image by Max Side
Resize an image proportionally so its longest dimension matches the target size.

```python
import cv2
from Jcy_utils import resize_by_maxside

# Read image using OpenCV
img = cv2.imread("input.jpg")

# Resize so the longest side is 512 pixels
resized_img = resize_by_maxside(img, max_side=512)

# Save the result
cv2.imwrite("resized_512.jpg", resized_img)
```

## 📦 How to Publish to PyPI

If you are the maintainer of this library, follow these steps to publish a new version to PyPI.

### 1. Prerequisites
Ensure you have the build tools installed:
```bash
pip install --upgrade build twine
```

### 2. Update Version
Modify the `version` string in `pyproject.toml` and `src/Jcy_utils/__init__.py` (e.g., change `0.0.1` to `0.0.2`).

### 3. Build the Package
Run the following command in the project root directory:
```bash
python -m build
```
This will generate distribution files in the `dist/` folder.

### 4. Upload to PyPI
Upload the newly built packages using Twine:
```bash
twine upload dist/*
```
You will be prompted for your PyPI API token (username: `__token__`).

## 🛠 Dependencies

- `numpy`
- `opencv-python`
- `Pillow`
- `tqdm`

## 📄 License

MIT License