{"id":49306956,"url":"https://github.com/yus314/vae-toolkit","last_synced_at":"2026-05-16T01:34:00.659Z","repository":{"id":312098261,"uuid":"1046345413","full_name":"Yus314/vae-toolkit","owner":"Yus314","description":"Stable Diffusion VAE toolkit image processing and model loading utilities","archived":false,"fork":false,"pushed_at":"2025-08-28T14:51:32.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-19T04:18:10.597Z","etag":null,"topics":["python","stable-diffusion","tool","vae"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Yus314.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-28T14:50:39.000Z","updated_at":"2026-03-04T09:01:33.000Z","dependencies_parsed_at":"2025-08-30T22:01:00.029Z","dependency_job_id":null,"html_url":"https://github.com/Yus314/vae-toolkit","commit_stats":null,"previous_names":["mdipcit/vae-toolkit"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Yus314/vae-toolkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yus314%2Fvae-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yus314%2Fvae-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yus314%2Fvae-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yus314%2Fvae-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yus314","download_url":"https://codeload.github.com/Yus314/vae-toolkit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yus314%2Fvae-toolkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32292958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python","stable-diffusion","tool","vae"],"created_at":"2026-04-26T10:01:46.338Z","updated_at":"2026-04-26T10:01:48.112Z","avatar_url":"https://github.com/Yus314.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VAE Toolkit\n\n[![PyPI version](https://badge.fury.io/py/vae-toolkit.svg)](https://badge.fury.io/py/vae-toolkit)\n[![Python Support](https://img.shields.io/pypi/pyversions/vae-toolkit.svg)](https://pypi.org/project/vae-toolkit/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA comprehensive toolkit for working with Stable Diffusion VAE models, providing image preprocessing utilities and model loading capabilities.\n\n## Features\n\n- 🖼️ **Image Processing**: Efficient image preprocessing and tensor conversions optimized for VAE models\n- 🚀 **Model Loading**: Easy loading of Stable Diffusion VAE models with automatic device selection\n- ⚡ **Performance**: Built-in caching and optimized transforms for faster processing\n- 🔧 **Flexible API**: Both high-level and low-level APIs for different use cases\n- 🛡️ **Type Safety**: Full type hints for better IDE support and code reliability\n- 🔐 **Secure**: No hardcoded tokens - authentication via environment variables only\n\n## Installation\n\n```bash\npip install vae-toolkit\n```\n\n### Optional Dependencies\n\nFor development:\n```bash\npip install vae-toolkit[dev]\n```\n\nFor testing:\n```bash\npip install vae-toolkit[test]\n```\n\nFor all extras:\n```bash\npip install vae-toolkit[all]\n```\n\n## Quick Start\n\n### Basic Image Processing\n\n```python\nfrom vae_toolkit import load_and_preprocess_image, tensor_to_pil\n\n# Load and preprocess an image for VAE encoding\ntensor, original_pil = load_and_preprocess_image(\"path/to/image.png\", target_size=512)\nprint(f\"Tensor shape: {tensor.shape}\")  # [1, 3, 512, 512]\nprint(f\"Value range: [{tensor.min():.2f}, {tensor.max():.2f}]\")  # [-1.00, 1.00]\n\n# Convert tensor back to PIL image\nreconstructed = tensor_to_pil(tensor)\nreconstructed.save(\"reconstructed.png\")\n```\n\n### Loading VAE Models\n\n```python\nfrom vae_toolkit import VAELoader\n\n# Initialize the loader\nloader = VAELoader()\n\n# Load Stable Diffusion v1.5 VAE\nvae, device = loader.load_sd_vae(\n    model_name=\"sd15\",  # or \"sd14\" for v1.4\n    device=\"auto\"        # automatically selects GPU/CPU\n)\n\nprint(f\"Model loaded on: {device}\")\n```\n\n### Complete VAE Workflow\n\n```python\nimport torch\nfrom vae_toolkit import load_and_preprocess_image, VAELoader, tensor_to_pil\n\n# Setup\nloader = VAELoader()\nvae, device = loader.load_sd_vae(\"sd14\")\n\n# Load and preprocess image\nimage_tensor, original = load_and_preprocess_image(\"input.jpg\", target_size=512)\nimage_tensor = image_tensor.to(device)\n\n# Encode to latent space\nwith torch.no_grad():\n    latent = vae.encode(image_tensor).latent_dist.sample()\n    print(f\"Latent shape: {latent.shape}\")  # [1, 4, 64, 64]\n\n# Decode back to image\nwith torch.no_grad():\n    decoded = vae.decode(latent).sample\n    \n# Save result\noutput_image = tensor_to_pil(decoded)\noutput_image.save(\"output.png\")\n```\n\n### Using the ImageProcessor Class\n\n```python\nfrom vae_toolkit import ImageProcessor\n\n# Create a processor with custom settings\nprocessor = ImageProcessor(\n    target_size=768,\n    normalize_mean=(0.5, 0.5, 0.5),\n    normalize_std=(0.5, 0.5, 0.5)\n)\n\n# Process multiple images with the same settings\nfor image_path in image_paths:\n    tensor, original = processor.load_and_preprocess(image_path)\n    # Process tensor...\n```\n\n## Authentication\n\nTo use models from Hugging Face Hub, set your token as an environment variable:\n\n```bash\nexport HF_TOKEN=\"your_huggingface_token\"\n# or\nexport HUGGING_FACE_HUB_TOKEN=\"your_huggingface_token\"\n```\n\n## API Reference\n\n### Image Processing Functions\n\n#### `load_and_preprocess_image(image_path, target_size=512)`\nLoads and preprocesses an image for VAE encoding.\n\n**Parameters:**\n- `image_path` (str | Path): Path to the input image\n- `target_size` (int): Target size for the square output image\n\n**Returns:**\n- `tuple[torch.Tensor, PIL.Image]`: Preprocessed tensor and original PIL image\n\n#### `tensor_to_pil(tensor)`\nConverts a tensor to PIL Image format.\n\n**Parameters:**\n- `tensor` (torch.Tensor): Input tensor with shape [C, H, W] or [1, C, H, W]\n\n**Returns:**\n- `PIL.Image`: RGB PIL image\n\n#### `pil_to_tensor(pil_image, target_size=None, normalize=True)`\nConverts a PIL image to tensor format.\n\n**Parameters:**\n- `pil_image` (PIL.Image): Input PIL image\n- `target_size` (int | None): Optional target size for resizing\n- `normalize` (bool): Whether to normalize to [-1, 1] range\n\n**Returns:**\n- `torch.Tensor`: Tensor with shape [3, H, W]\n\n### VAE Loader\n\n#### `VAELoader`\nMain class for loading and managing Stable Diffusion VAE models.\n\n**Methods:**\n- `load_sd_vae(model_name=\"sd14\", device=\"auto\", token=None, use_cache=True)`\n  - Loads a Stable Diffusion VAE model\n  - Returns: `tuple[AutoencoderKL, torch.device]`\n  \n- `get_optimal_device(preferred_device=\"auto\")`\n  - Determines the best available device\n  - Returns: `torch.device`\n  \n- `clear_cache()`\n  - Clears the model cache to free memory\n\n### Model Configuration\n\n#### `get_model_config(model_name)`\nGets configuration for a specific model.\n\n#### `list_available_models()`\nLists all available model identifiers.\n\n#### `add_model_config(model_name, config)`\nAdds a custom model configuration.\n\n## Available Models\n\n- `sd14`: Stable Diffusion v1.4 VAE\n- `sd15`: Stable Diffusion v1.5 VAE\n\n## Error Handling\n\nThe toolkit includes custom exceptions for better error handling:\n\n```python\nfrom vae_toolkit import ImageProcessingError\n\ntry:\n    tensor, _ = load_and_preprocess_image(\"invalid_path.jpg\")\nexcept ImageProcessingError as e:\n    print(f\"Failed to process image: {e}\")\n```\n\n## Performance Tips\n\n1. **Use caching**: The VAELoader caches models by default to avoid reloading\n2. **Batch processing**: Process multiple images together when possible\n3. **Device selection**: Use \"auto\" for automatic GPU/CPU selection\n4. **Memory management**: Call `loader.clear_cache()` when switching between models\n\n## Requirements\n\n- Python \u003e= 3.8\n- PyTorch \u003e= 2.0.0\n- torchvision \u003e= 0.15.0\n- Pillow \u003e= 9.0.0\n- numpy \u003e= 1.20.0\n- diffusers \u003e= 0.20.0\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## Testing\n\nRun tests with pytest:\n\n```bash\n# Install test dependencies\npip install vae-toolkit[test]\n\n# Run tests\npytest\n\n# Run with coverage\npytest --cov=vae_toolkit\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Citation\n\nIf you use this toolkit in your research, please cite:\n\n```bibtex\n@software{vae-toolkit,\n  author = {Yus314},\n  title = {VAE Toolkit: Stable Diffusion VAE utilities},\n  year = {2024},\n  url = {https://github.com/mdipcit/vae-toolkit}\n}\n```\n\n## Acknowledgments\n\n- Built on top of the amazing [diffusers](https://github.com/huggingface/diffusers) library\n- Inspired by the Stable Diffusion community\n\n## Support\n\nFor issues and questions, please use the [GitHub Issues](https://github.com/mdipcit/vae-toolkit/issues) page.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyus314%2Fvae-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyus314%2Fvae-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyus314%2Fvae-toolkit/lists"}