Metadata-Version: 2.1
Name: capybara_docsaid
Version: 0.4.0
Summary: OpenCV with ONNX Runtime Inference Toolkit.
Home-page: https://github.com/DocsaidLab/Capybara.git
License: Apache License 2.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyheif; platform_system == "Linux"
Requires-Dist: dacite
Requires-Dist: psutil
Requires-Dist: requests
Requires-Dist: onnx
Requires-Dist: colored
Requires-Dist: numpy<2.0.0
Requires-Dist: pdf2image
Requires-Dist: ujson
Requires-Dist: pyyaml
Requires-Dist: tqdm
Requires-Dist: pybase64
Requires-Dist: PyTurboJPEG
Requires-Dist: dill
Requires-Dist: networkx
Requires-Dist: natsort
Requires-Dist: flask
Requires-Dist: shapely
Requires-Dist: piexif
Requires-Dist: matplotlib
Requires-Dist: opencv-python==4.9.0.80
Requires-Dist: onnxruntime==1.20.1; platform_system == "Darwin"
Requires-Dist: onnxruntime_gpu==1.20.1; platform_system == "Linux"

[**English**](./README.md) | [中文](./README_tw.md)

# Capybara

<p align="left">
    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202-dfd.svg"></a>
    <a href=""><img src="https://img.shields.io/badge/python-3.10+-aff.svg"></a>
    <a href="https://github.com/DocsaidLab/Capybara/releases"><img src="https://img.shields.io/github/v/release/DocsaidLab/Capybara?color=ffa"></a>
    <a href="https://pypi.org/project/capybara_docsaid/"><img src="https://img.shields.io/pypi/v/capybara_docsaid.svg"></a>
</p>

## Introduction

![title](https://raw.githubusercontent.com/DocsaidLab/Capybara/refs/heads/main/docs/title.webp)

This project is an image processing and deep learning toolkit, mainly consisting of the following parts:

- **Vision**: Provides functionalities related to computer vision, such as image and video processing.
- **Structures**: Modules for handling structured data, such as BoundingBox and Polygon.
- **ONNXEngine**: Provides ONNX inference functionalities, supporting ONNX format models.
- **Utils**: Contains utility functions that do not belong to other modules.
- **Tests**: Includes test code for various functions to verify their correctness.

## Technical Documentation

For more detailed information on installation and usage, please refer to the [**Capybara Documents**](https://docsaid.org/en/docs/capybara).

The document provides a detailed explanation of this project and answers to frequently asked questions.

## Installation

Before starting the installation of Capybara, ensure that your system meets the following requirements:

### Python Version

- Python 3.10 or later is required.

### Dependency Packages

Please install the necessary system packages according to your operating system:

- **Ubuntu**

  ```bash
  sudo apt install libturbojpeg exiftool ffmpeg libheif-dev
  ```

- **MacOS**

  ```bash
  brew install jpeg-turbo exiftool ffmpeg
  ```

  - **Special Notes**: After testing, there are some known issues when using libheif on macOS, including:

    1. **Generated HEIC files cannot be opened**: On macOS, HEIC files generated by libheif may not open with certain applications. This may be related to image dimensions, particularly when the image width or height is odd, causing compatibility issues.

    2. **Compilation errors**: When compiling libheif on macOS, you may encounter undefined symbol errors related to ffmpeg decoders. This could be caused by incorrect compilation options or dependency settings.

    3. **Example programs do not run**: On macOS Sonoma, the example programs of libheif might fail with dynamic link errors, indicating that `libheif.1.dylib` is missing. This might be related to dynamic library path settings.

    Due to these issues, we currently only run libheif on Ubuntu, and macOS support will be addressed in future versions.

### pdf2image Dependency

pdf2image is a Python module used to convert PDF documents to images. Make sure the following tools are installed on your system:

- MacOS: Install poppler

  ```bash
  brew install poppler
  ```

- Linux: Most distributions already include `pdftoppm` and `pdftocairo`. If not, install them using:

  ```bash
  sudo apt install poppler-utils
  ```

### ONNXRuntime GPU Dependencies

To use ONNXRuntime for GPU-accelerated inference, ensure that you have an appropriate version of CUDA installed. Here's an example:

```bash
sudo apt install cuda-12-4
# Add to .bashrc
echo 'export PATH=/usr/local/cuda-12.4/bin${PATH:+:${PATH}}' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}' >> ~/.bashrc
```

### Installation via PyPI

1. Install the package from PyPI:

   ```bash
   pip install capybara-docsaid
   ```

2. Verify the installation:

   ```bash
   python -c "import capybara; print(capybara.__version__)"
   ```

3. If the version number is displayed, the installation was successful.

### Installation via Git Clone

1. Clone this repository:

   ```bash
   git clone https://github.com/DocsaidLab/Capybara.git
   ```

2. Install the wheel package:

   ```bash
   pip install wheel
   ```

3. Build the wheel file:

   ```bash
   cd Capybara
   python setup.py bdist_wheel
   ```

4. Install the built wheel file:

   ```bash
   pip install dist/capybara_docsaid-*-py3-none-any.whl
   ```

### Installation via Docker

To avoid environment conflicts during deployment or collaborative development, it's recommended to use Docker. Here's a brief guide:

1. Clone this repository:

   ```bash
   git clone https://github.com/DocsaidLab/Capybara.git
   ```

2. Enter the project directory and run the build script:

   ```bash
   cd Capybara
   bash docker/build.bash
   ```

   This will build an image using the [**Dockerfile**](https://github.com/DocsaidLab/Capybara/blob/main/docker/Dockerfile) in the project. The image is based on `nvcr.io/nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04` by default, providing the CUDA environment required for ONNXRuntime inference.

3. After the build is complete, mount the working directory and run the program:

   ```bash
   docker run -v ${PWD}:/code -it docsaid_training_base_image your_scripts.py
   ```

   To enable GPU acceleration, add `--gpus all` when running the command.

#### gosu Permissions Issues

If you encounter issues with file ownership as root when running scripts inside the container, causing permission problems, you can use `gosu` to switch users in the Dockerfile. Specify `USER_ID` and `GROUP_ID` when starting the container to avoid frequent permission adjustments in collaborative development.

For details, refer to the technical documentation: [**Integrating gosu Configuration**](https://docsaid.org/en/docs/capybara/advance/#integrating-gosu-configuration)

1. Install `gosu`:

   ```dockerfile
   RUN apt-get update && apt-get install -y gosu
   ```

2. Use `gosu` in the container start command to switch to a non-root user for file read/write operations.

   ```dockerfile
   # Create the entrypoint script
   RUN printf '#!/bin/bash\n\
       if [ ! -z "$USER_ID" ] && [ ! -z "$GROUP_ID" ]; then\n\
           groupadd -g "$GROUP_ID" -o usergroup\n\
           useradd --shell /bin/bash -u "$USER_ID" -g "$GROUP_ID" -o -c "" -m user\n\
           export HOME=/home/user\n\
           chown -R "$USER_ID":"$GROUP_ID" /home/user\n\
           chown -R "$USER_ID":"$GROUP_ID" /code\n\
       fi\n\
       \n\
       # Check for parameters\n\
       if [ $# -gt 0 ]; then\n\
           exec gosu ${USER_ID:-0}:${GROUP_ID:-0} python "$@"\n\
       else\n\
           exec gosu ${USER_ID:-0}:${GROUP_ID:-0} bash\n\
       fi' > "$ENTRYPOINT_SCRIPT"

   RUN chmod +x "$ENTRYPOINT_SCRIPT"

   ENTRYPOINT ["/bin/bash", "/entrypoint.sh"]
   ```

For more advanced configuration, refer to [**NVIDIA Container Toolkit**](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) and the official [**docker**](https://docs.docker.com/) documentation.

## Testing

This project uses `pytest` for unit testing, and users can run the tests themselves to verify the correctness of the functionalities. To install and run the tests, use the following commands:

```bash
pip install pytest
python -m pytest -vv tests
```

Once completed, you can check if all modules are functioning properly. If any issues arise, first check the environment settings and package versions.

If the problem persists, please report it in the Issue section.
