Metadata-Version: 2.5
Name: datasets-islr-libras
Version: 0.1.0
Summary: Lightweight data loading and metadata management library for LIBRAS datasets.
Project-URL: Homepage, https://github.com/giolucasd/datasets-islr-libras
Project-URL: Repository, https://github.com/giolucasd/datasets-islr-libras
Project-URL: Issues, https://github.com/giolucasd/datasets-islr-libras/issues
Author-email: Giovanne Mariano <giolucasd@gmail.com>
License: MIT
License-File: LICENSE
Keywords: computer-vision,dataset,islr,libras,machine-learning,sign-language
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.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: pandas>=3.0.0
Description-Content-Type: text/markdown

# datasets-islr-libras <!-- omit from toc -->

A modular Python library providing standardized data loading and metadata management for Brazilian Sign Language (LIBRAS) datasets focused on Isolated Sign Language Recognition (ISLR).

The package is built with a framework-agnostic architecture (pure Python and Pandas), allowing dataset outputs to be directly integrated into PyTorch, TensorFlow, JAX, or custom OpenCV processing pipelines.

- [1. Installation](#1-installation)
- [2. Supported Datasets](#2-supported-datasets)
  - [2.1. LIBRAS-EQT-UECE](#21-libras-eqt-uece)
- [3. Quick Start](#3-quick-start)
  - [3.1. Basic Dataset Loading](#31-basic-dataset-loading)
  - [3.2. 5-Fold Cross-Validation](#32-5-fold-cross-validation)
  - [3.3. Manual Signer Selection](#33-manual-signer-selection)
- [4. Configuration Reference (`LibrasEQTConfig`)](#4-configuration-reference-libraseqtconfig)
- [5. References \& Papers](#5-references--papers)

## 1. Installation

Install using `pip`:

```bash
pip install datasets-islr-libras

```

Or using `uv`:

```bash
uv add datasets-islr-libras

```

## 2. Supported Datasets

`datasets-islr-libras` is designed to support multiple LIBRAS datasets under a standardized API. Currently supported datasets:

### 2.1. LIBRAS-EQT-UECE

The **LIBRAS-EQT-UECE** dataset contains video recordings of LIBRAS signs recorded across 6 informants with 6 repetitions each. For isolated sign recognition, this library filters and standardizes **48 isolated sign classes** (single LIBRAS lexical items and distinct gestures).

* **Dataset Downloads**: Download the raw dataset directly from Zenodo at [https://zenodo.org/records/21398895](https://zenodo.org/records/21398895).
* **Cross-Validation**: Includes built-in support for the per-sign 5-fold signer-stratified scheme (3 train signers : 1 validation signer : 1 test signer per fold).

Expected extracted directory layout:

```text
LIBRAS-EQT-UECE/
├── 100_Cair./
│   ├── INFORMANTE 1/
│   │   ├── video_1.mp4
│   │   └── ...
│   └── INFORMANTE 2/
├── 103_Não sei./
└── ...

```

## 3. Quick Start

### 3.1. Basic Dataset Loading

```python
from islr_libras_datasets.libras_eqt_uece import LibrasEQTConfig, LibrasEQTDataset

# Initialize configuration for LIBRAS-EQT-UECE
config = LibrasEQTConfig(
    root="/path/to/LIBRAS-EQT-UECE",
    split="all",        # Options: 'all', 'train', 'val', 'test', or 'fold_X'
    target="sign_index" # Options: 'sign_index', 'sign_gloss'
)

# Instantiate dataset
dataset = LibrasEQTDataset(config)

print(f"Total instances: {len(dataset)}")
print(f"Total isolated classes: {len(dataset.labels)}")

# Inspect a single sample
sample = dataset[0]
print(sample)
# Output:
# {
#     'instance_id': '100_INFORMANTE 1_IMG_4550',
#     'video_path': '/path/to/LIBRAS-EQT-UECE/100_Cair./INFORMANTE 1/IMG_4550.mp4',
#     'target': 0,
#     'gloss': 'Cair.',
#     'item_id': 100,
#     'signer': 'INFORMANTE 1'
# }

```

### 3.2. 5-Fold Cross-Validation

Iterate through the 5-fold stratified cross-validation splits (rotating held-out per-item informants across train, validation, and test partitions):

```python
dataset_root = "/path/to/LIBRAS-EQT-UECE"

for fold in range(5):
    train_cfg = LibrasEQTConfig(root=dataset_root, split="train", fold=fold)
    val_cfg   = LibrasEQTConfig(root=dataset_root, split="val", fold=fold)
    test_cfg  = LibrasEQTConfig(root=dataset_root, split="test", fold=fold)

    train_ds = LibrasEQTDataset(train_cfg)
    val_ds   = LibrasEQTDataset(val_cfg)
    test_ds  = LibrasEQTDataset(test_cfg)

    print(f"Fold {fold} | Train: {len(train_ds)} | Val: {len(val_ds)} | Test: {len(test_ds)}")

```

### 3.3. Manual Signer Selection

You can specify exact signers, overriding the cross-validation fold partition:

```python
config = LibrasEQTConfig(
    root="/path/to/LIBRAS-EQT-UECE",
    signers=("1", "2", "3")  # Filters for 'INFORMANTE 1', 'INFORMANTE 2', 'INFORMANTE 3'
)

dataset = LibrasEQTDataset(config)

```

## 4. Configuration Reference (`LibrasEQTConfig`)

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `root` | `str` | *Required* | Path to the dataset root directory. |
| `split` | `str` | `"all"` | Partition selection: `"all"`, `"train"`, `"val"`, `"test"`, or `"fold_X"`. |
| `fold` | `int` | `None` | `None` | Active fold index (`0` to `4`) for 5-fold cross-validation. |
| `signers` | `Sequence[str]` | `None` | `None` | Explicit list of signers to include (e.g., `("1", "2")`). |
| `target` | `str` | `"sign_index"` | Target type returned: `"sign_index"` (integer) or `"sign_gloss"` (string). |
| `sequence_max_length` | `int` | `None` | `None` | Optional max frame sequence length setting. |

## 5. References & Papers

If you use datasets supported by this package in your research, please consult and cite the corresponding dataset publication:

* **LIBRAS-EQT-UECE Paper & Record**: Available on Zenodo at [https://zenodo.org/records/20497742](https://zenodo.org/records/20497742)
