# realutils
[](https://pypi.org/project/dghs-realutils/)
[](https://github.com/deepghs/realutils/actions?query=workflow%3A%22Code+Test%22)
[](https://github.com/deepghs/realutils/actions?query=workflow%3A%22Package+Release%22)
[](https://codecov.io/gh/deepghs/realutils)
[](https://discord.gg/TwdHJ42N72)
[](https://github.com/deepghs/realutils/stargazers)
[](https://github.com/deepghs/realutils/network)
[](https://github.com/deepghs/realutils/issues)
[](https://github.com/deepghs/realutils/pulls)
[](https://github.com/deepghs/realutils/graphs/contributors)
[](https://github.com/deepghs/realutils/blob/master/LICENSE)
A convenient and user-friendly image data processing library that integrates various advanced image processing models.
## Installation
You can simply install it with `pip` command line from the official PyPI site.
```shell
pip install dghs-realutils
```
If your operating environment includes a available GPU, you can use the following installation command to achieve higher
performance:
```shell
pip install dghs-realutils[gpu]
```
For more information about installation, you can refer
to [Installation](https://deepghs.github.io/realutils/main/tutorials/installation/index.html).
## Supported or Developing Features
`realutils` includes many generic usable features which are available on non-GPU device.
For detailed descriptions and examples, please refer to the
[official documentation](https://deepghs.github.io/realutils/main/index.html).
Here, we won't go into each of them individually.
### Real Human Photo Tagger
We have tagger for real human photos, like this
We can use `get_idolsankaku_tags` to tag them
```python
from realutils.tagging import get_idolsankaku_tags
rating, general, character = get_idolsankaku_tags('idolsankaku/1.jpg')
print(rating)
# {'safe': 0.748395562171936, 'questionable': 0.22442740201950073, 'explicit': 0.022273868322372437}
print(general)
# {'1girl': 0.7476911544799805, 'asian': 0.3681548237800598, 'skirt': 0.8094233274459839, 'solo': 0.44033104181289673, 'blouse': 0.7909733057022095, 'pantyhose': 0.8893758654594421, 'long_hair': 0.7415428161621094, 'brown_hair': 0.4968719780445099, 'sitting': 0.49351146817207336, 'high_heels': 0.41397374868392944, 'outdoors': 0.5279690623283386, 'non_nude': 0.4075928330421448}
print(character)
# {}
rating, general, character = get_idolsankaku_tags('idolsankaku/7.jpg')
print(rating)
# {'safe': 0.9750080704689026, 'questionable': 0.0257779061794281, 'explicit': 0.0018109679222106934}
print(general)
# {'1girl': 0.5759814381599426, 'asian': 0.46296364068984985, 'skirt': 0.9698911905288696, 'solo': 0.6263223886489868, 'female': 0.5258357524871826, 'blouse': 0.8670071959495544, 'twintails': 0.9444552659988403, 'pleated_skirt': 0.8233045935630798, 'miniskirt': 0.8354354500770569, 'long_hair': 0.8752110004425049, 'looking_at_viewer': 0.4927205741405487, 'detached_sleeves': 0.9382797479629517, 'shirt': 0.8463951945304871, 'tie': 0.8901710510253906, 'aqua_hair': 0.9376567006111145, 'armpit': 0.5968506336212158, 'arms_up': 0.9492673873901367, 'sleeveless_blouse': 0.9789504408836365, 'black_thighhighs': 0.41496211290359497, 'sleeveless': 0.9865490198135376, 'default_costume': 0.36392033100128174, 'sleeveless_shirt': 0.9865082502365112, 'very_long_hair': 0.3988983631134033}
print(character)
# {'hatsune_miku': 0.9460012912750244}
```
For more details,
see: [documentation of get_idolsankaku_tags](https://dghs-realutils.deepghs.org/main/api_doc/tagging/idolsankaku.html#get-idolsankaku-tags).
### Generic Object Detection
We use official YOLO models the generic purpose of object detections.
We can use `detect_by_yolo` for generic object detection
```python
from realutils.detect import detect_by_yolo
print(detect_by_yolo('yolo/unsplash_aJafJ0sLo6o.jpg'))
# [((450, 317, 567, 599), 'person', 0.9004617929458618)]
print(detect_by_yolo('yolo/unsplash_n4qQGOBgI7U.jpg'))
# [((73, 101, 365, 409), 'vase', 0.9098997116088867), ((441, 215, 659, 428), 'vase', 0.622944176197052), ((5, 1, 428, 377), 'potted plant', 0.5178268551826477)]
print(detect_by_yolo('yolo/unsplash_vUNQaTtZeOo.jpg'))
# [((381, 103, 676, 448), 'bird', 0.9061452150344849)]
print(detect_by_yolo('yolo/unsplash_YZOqXWF_9pk.jpg'))
# [((315, 100, 690, 532), 'horse', 0.9453459978103638), ((198, 181, 291, 256), 'horse', 0.917123556137085), ((145, 173, 180, 249), 'horse', 0.7972317337989807), ((660, 138, 701, 170), 'horse', 0.4843617379665375)]
```
More models are hosted on [huggingface repository](https://huggingface.co/deepghs/yolos).
An online demo are provided as well, you can try [it](https://huggingface.co/spaces/deepghs/yolos) out.
### Face Detection
We use YOLO models from [deepghs/real_face_detection](https://huggingface.co/deepghs/real_face_detection) for face
detection.
We can use `detect_faces` for face detection
```python
from realutils.detect import detect_faces
print(detect_faces('yolo/solo.jpg'))
# [((168, 79, 245, 199), 'face', 0.7996422052383423)]
print(detect_faces('yolo/2girls.jpg'))
# [((721, 152, 1082, 726), 'face', 0.8811314702033997), ((158, 263, 509, 714), 'face', 0.8745490908622742)]
print(detect_faces('yolo/3+cosplay.jpg'))
# [((351, 228, 410, 302), 'face', 0.8392542600631714), ((384, 63, 427, 116), 'face', 0.8173024654388428), ((195, 109, 246, 161), 'face', 0.8126493692398071)]
print(detect_faces('yolo/multiple.jpg'))
# [((1074, 732, 1258, 987), 'face', 0.8792377710342407), ((1378, 536, 1541, 716), 'face', 0.8607611656188965), ((554, 295, 759, 557), 'face', 0.8541485071182251), ((897, 315, 1068, 520), 'face', 0.8539882898330688), ((1194, 230, 1329, 403), 'face', 0.8324605226516724)]
```
More models are hosted on [huggingface repository](https://huggingface.co/deepghs/real_face_detection).
An online demo are provided as well, you can try [it](https://huggingface.co/spaces/deepghs/real_object_detection) out.
### Feature Extractor
We support DINOv2-based image feature extractor, like this
```python
from realutils.metrics import get_dinov2_embedding
embedding = get_dinov2_embedding('unsplash_0aLd44ICcpg.jpg')
print(embedding.shape)
# (768,)
```
You can use this embedding, calculating their cosine similarities to measure their visual similarities.
### Image-Text Models
We support both CLIP and SigLIP for multimodal alignment operations, like this
* CLIP
```python
from realutils.metrics.clip import classify_with_clip
print(classify_with_clip(
images=[
'xlip/1.jpg',
'xlip/2.jpg'
],
texts=[
'a photo of a cat',
'a photo of a dog',
'a photo of a human',
],
))
# array([[0.98039913, 0.00506729, 0.01453355],
# [0.05586662, 0.02006196, 0.92407143]], dtype=float32)
```
* SigLIP
```python
from realutils.metrics.siglip import classify_with_siglip
print(classify_with_siglip(
images=[
'xlip/1.jpg',
'xlip/2.jpg',
],
texts=[
'a photo of a cat',
'a photo of 2 cats',
'a photo of 2 dogs',
'a photo of a woman',
],
))
# array([[1.3782851e-03, 2.7010253e-01, 9.7517688e-05, 3.6702781e-09],
# [3.3248414e-06, 2.2294161e-07, 1.9753381e-09, 2.2561464e-06]],
# dtype=float32)
```
For more details, you can take a look at:
* [Documentation of realutils.metrics.clip](https://dghs-realutils.deepghs.org/main/api_doc/metrics/clip.html)
* [Models of CLIP](https://huggingface.co/deepghs/clip_onnx)
* [Documentation of realutils.metrics.siglip](https://dghs-realutils.deepghs.org/main/api_doc/metrics/siglip.html)
* [Models of SigLIP](https://huggingface.co/deepghs/siglip_onnx)
Raw data
{
"_id": null,
"home_page": "https://github.com/deepghs/realutils",
"name": "dghs-realutils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "image-processing, computer-vision, deep-learning, data-augmentation",
"author": "narugo1992",
"author_email": "narugo1992@deepghs.org",
"download_url": "https://files.pythonhosted.org/packages/f1/34/f473d67bf2f9efc0fe1465a3303646d5486c8775ac23aa1086da24c55c2e/dghs_realutils-0.0.4.tar.gz",
"platform": null,
"description": "# realutils\n\n[](https://pypi.org/project/dghs-realutils/)\n\n\n\n\n[](https://github.com/deepghs/realutils/actions?query=workflow%3A%22Code+Test%22)\n[](https://github.com/deepghs/realutils/actions?query=workflow%3A%22Package+Release%22)\n[](https://codecov.io/gh/deepghs/realutils)\n\n[](https://discord.gg/TwdHJ42N72)\n\n[](https://github.com/deepghs/realutils/stargazers)\n[](https://github.com/deepghs/realutils/network)\n\n[](https://github.com/deepghs/realutils/issues)\n[](https://github.com/deepghs/realutils/pulls)\n[](https://github.com/deepghs/realutils/graphs/contributors)\n[](https://github.com/deepghs/realutils/blob/master/LICENSE)\n\nA convenient and user-friendly image data processing library that integrates various advanced image processing models.\n\n## Installation\n\nYou can simply install it with `pip` command line from the official PyPI site.\n\n```shell\npip install dghs-realutils\n```\n\nIf your operating environment includes a available GPU, you can use the following installation command to achieve higher\nperformance:\n\n```shell\npip install dghs-realutils[gpu]\n```\n\nFor more information about installation, you can refer\nto [Installation](https://deepghs.github.io/realutils/main/tutorials/installation/index.html).\n\n## Supported or Developing Features\n\n`realutils` includes many generic usable features which are available on non-GPU device.\nFor detailed descriptions and examples, please refer to the\n[official documentation](https://deepghs.github.io/realutils/main/index.html).\nHere, we won't go into each of them individually.\n\n### Real Human Photo Tagger\n\nWe have tagger for real human photos, like this\n\n\n\nWe can use `get_idolsankaku_tags` to tag them\n\n```python\nfrom realutils.tagging import get_idolsankaku_tags\n\nrating, general, character = get_idolsankaku_tags('idolsankaku/1.jpg')\nprint(rating)\n# {'safe': 0.748395562171936, 'questionable': 0.22442740201950073, 'explicit': 0.022273868322372437}\nprint(general)\n# {'1girl': 0.7476911544799805, 'asian': 0.3681548237800598, 'skirt': 0.8094233274459839, 'solo': 0.44033104181289673, 'blouse': 0.7909733057022095, 'pantyhose': 0.8893758654594421, 'long_hair': 0.7415428161621094, 'brown_hair': 0.4968719780445099, 'sitting': 0.49351146817207336, 'high_heels': 0.41397374868392944, 'outdoors': 0.5279690623283386, 'non_nude': 0.4075928330421448}\nprint(character)\n# {}\n\nrating, general, character = get_idolsankaku_tags('idolsankaku/7.jpg')\nprint(rating)\n# {'safe': 0.9750080704689026, 'questionable': 0.0257779061794281, 'explicit': 0.0018109679222106934}\nprint(general)\n# {'1girl': 0.5759814381599426, 'asian': 0.46296364068984985, 'skirt': 0.9698911905288696, 'solo': 0.6263223886489868, 'female': 0.5258357524871826, 'blouse': 0.8670071959495544, 'twintails': 0.9444552659988403, 'pleated_skirt': 0.8233045935630798, 'miniskirt': 0.8354354500770569, 'long_hair': 0.8752110004425049, 'looking_at_viewer': 0.4927205741405487, 'detached_sleeves': 0.9382797479629517, 'shirt': 0.8463951945304871, 'tie': 0.8901710510253906, 'aqua_hair': 0.9376567006111145, 'armpit': 0.5968506336212158, 'arms_up': 0.9492673873901367, 'sleeveless_blouse': 0.9789504408836365, 'black_thighhighs': 0.41496211290359497, 'sleeveless': 0.9865490198135376, 'default_costume': 0.36392033100128174, 'sleeveless_shirt': 0.9865082502365112, 'very_long_hair': 0.3988983631134033}\nprint(character)\n# {'hatsune_miku': 0.9460012912750244}\n```\n\nFor more details,\nsee: [documentation of get_idolsankaku_tags](https://dghs-realutils.deepghs.org/main/api_doc/tagging/idolsankaku.html#get-idolsankaku-tags).\n\n### Generic Object Detection\n\nWe use official YOLO models the generic purpose of object detections.\n\n\n\nWe can use `detect_by_yolo` for generic object detection\n\n```python\nfrom realutils.detect import detect_by_yolo\n\nprint(detect_by_yolo('yolo/unsplash_aJafJ0sLo6o.jpg'))\n# [((450, 317, 567, 599), 'person', 0.9004617929458618)]\nprint(detect_by_yolo('yolo/unsplash_n4qQGOBgI7U.jpg'))\n# [((73, 101, 365, 409), 'vase', 0.9098997116088867), ((441, 215, 659, 428), 'vase', 0.622944176197052), ((5, 1, 428, 377), 'potted plant', 0.5178268551826477)]\nprint(detect_by_yolo('yolo/unsplash_vUNQaTtZeOo.jpg'))\n# [((381, 103, 676, 448), 'bird', 0.9061452150344849)]\nprint(detect_by_yolo('yolo/unsplash_YZOqXWF_9pk.jpg'))\n# [((315, 100, 690, 532), 'horse', 0.9453459978103638), ((198, 181, 291, 256), 'horse', 0.917123556137085), ((145, 173, 180, 249), 'horse', 0.7972317337989807), ((660, 138, 701, 170), 'horse', 0.4843617379665375)]\n```\n\nMore models are hosted on [huggingface repository](https://huggingface.co/deepghs/yolos).\nAn online demo are provided as well, you can try [it](https://huggingface.co/spaces/deepghs/yolos) out.\n\n### Face Detection\n\nWe use YOLO models from [deepghs/real_face_detection](https://huggingface.co/deepghs/real_face_detection) for face\ndetection.\n\n\n\nWe can use `detect_faces` for face detection\n\n```python\nfrom realutils.detect import detect_faces\n\nprint(detect_faces('yolo/solo.jpg'))\n# [((168, 79, 245, 199), 'face', 0.7996422052383423)]\nprint(detect_faces('yolo/2girls.jpg'))\n# [((721, 152, 1082, 726), 'face', 0.8811314702033997), ((158, 263, 509, 714), 'face', 0.8745490908622742)]\nprint(detect_faces('yolo/3+cosplay.jpg'))\n# [((351, 228, 410, 302), 'face', 0.8392542600631714), ((384, 63, 427, 116), 'face', 0.8173024654388428), ((195, 109, 246, 161), 'face', 0.8126493692398071)]\nprint(detect_faces('yolo/multiple.jpg'))\n# [((1074, 732, 1258, 987), 'face', 0.8792377710342407), ((1378, 536, 1541, 716), 'face', 0.8607611656188965), ((554, 295, 759, 557), 'face', 0.8541485071182251), ((897, 315, 1068, 520), 'face', 0.8539882898330688), ((1194, 230, 1329, 403), 'face', 0.8324605226516724)]\n```\n\nMore models are hosted on [huggingface repository](https://huggingface.co/deepghs/real_face_detection).\nAn online demo are provided as well, you can try [it](https://huggingface.co/spaces/deepghs/real_object_detection) out.\n\n### Feature Extractor\n\nWe support DINOv2-based image feature extractor, like this\n\n```python\nfrom realutils.metrics import get_dinov2_embedding\n\nembedding = get_dinov2_embedding('unsplash_0aLd44ICcpg.jpg')\nprint(embedding.shape)\n# (768,)\n```\n\nYou can use this embedding, calculating their cosine similarities to measure their visual similarities.\n\n### Image-Text Models\n\nWe support both CLIP and SigLIP for multimodal alignment operations, like this\n\n* CLIP\n\n```python\nfrom realutils.metrics.clip import classify_with_clip\n\nprint(classify_with_clip(\n images=[\n 'xlip/1.jpg',\n 'xlip/2.jpg'\n ],\n texts=[\n 'a photo of a cat',\n 'a photo of a dog',\n 'a photo of a human',\n ],\n))\n# array([[0.98039913, 0.00506729, 0.01453355],\n# [0.05586662, 0.02006196, 0.92407143]], dtype=float32)\n```\n\n* SigLIP\n\n```python\nfrom realutils.metrics.siglip import classify_with_siglip\n\nprint(classify_with_siglip(\n images=[\n 'xlip/1.jpg',\n 'xlip/2.jpg',\n ],\n texts=[\n 'a photo of a cat',\n 'a photo of 2 cats',\n 'a photo of 2 dogs',\n 'a photo of a woman',\n ],\n))\n# array([[1.3782851e-03, 2.7010253e-01, 9.7517688e-05, 3.6702781e-09],\n# [3.3248414e-06, 2.2294161e-07, 1.9753381e-09, 2.2561464e-06]],\n# dtype=float32)\n```\n\nFor more details, you can take a look at:\n\n* [Documentation of realutils.metrics.clip](https://dghs-realutils.deepghs.org/main/api_doc/metrics/clip.html)\n* [Models of CLIP](https://huggingface.co/deepghs/clip_onnx)\n* [Documentation of realutils.metrics.siglip](https://dghs-realutils.deepghs.org/main/api_doc/metrics/siglip.html)\n* [Models of SigLIP](https://huggingface.co/deepghs/siglip_onnx)\n\n",
"bugtrack_url": null,
"license": "GNU Lesser General Public License v3 or later (LGPLv3+)",
"summary": "A convenient and user-friendly image data processing library that integrates various advanced image processing models.",
"version": "0.0.4",
"project_urls": {
"Homepage": "https://github.com/deepghs/realutils"
},
"split_keywords": [
"image-processing",
" computer-vision",
" deep-learning",
" data-augmentation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "14b2102a7d7851500a2b6664cdae8932b690be76b164553e704ba7a0cd777013",
"md5": "4d4242c86d86a7112fcf5b68019b3956",
"sha256": "a72ad07e3d63de9e0385e4a2c70035791231a9129095e53dfb63b4becb569a79"
},
"downloads": -1,
"filename": "dghs_realutils-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4d4242c86d86a7112fcf5b68019b3956",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 26995,
"upload_time": "2025-02-22T02:07:32",
"upload_time_iso_8601": "2025-02-22T02:07:32.948645Z",
"url": "https://files.pythonhosted.org/packages/14/b2/102a7d7851500a2b6664cdae8932b690be76b164553e704ba7a0cd777013/dghs_realutils-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f134f473d67bf2f9efc0fe1465a3303646d5486c8775ac23aa1086da24c55c2e",
"md5": "4c8b66d0d4375d428c57ead38977ecb5",
"sha256": "8e2a11d32e37c7df1f0aa44aaccfca2f295107b96e60533a3ee1a1962227b345"
},
"downloads": -1,
"filename": "dghs_realutils-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "4c8b66d0d4375d428c57ead38977ecb5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 21224,
"upload_time": "2025-02-22T02:07:34",
"upload_time_iso_8601": "2025-02-22T02:07:34.944072Z",
"url": "https://files.pythonhosted.org/packages/f1/34/f473d67bf2f9efc0fe1465a3303646d5486c8775ac23aa1086da24c55c2e/dghs_realutils-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-22 02:07:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "deepghs",
"github_project": "realutils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "hbutils",
"specs": [
[
">=",
"0.9.0"
]
]
},
{
"name": "pillow",
"specs": []
},
{
"name": "numpy",
"specs": [
[
"<",
"2"
]
]
},
{
"name": "scikit-learn",
"specs": []
},
{
"name": "huggingface_hub",
"specs": []
},
{
"name": "tqdm",
"specs": []
},
{
"name": "opencv-python",
"specs": []
},
{
"name": "opencv-contrib-python",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "scipy",
"specs": []
},
{
"name": "emoji",
"specs": [
[
"<",
"2.12"
],
[
">=",
"2.5.0"
]
]
},
{
"name": "pilmoji",
"specs": [
[
">=",
"1.3.0"
]
]
},
{
"name": "deprecation",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "hfutils",
"specs": [
[
">=",
"0.4.2"
]
]
},
{
"name": "filelock",
"specs": []
},
{
"name": "dghs-imgutils",
"specs": [
[
">=",
"0.11.0"
]
]
},
{
"name": "tokenizers",
"specs": [
[
">=",
"0.20.0"
]
]
},
{
"name": "tokenizers",
"specs": [
[
"<",
"0.21"
],
[
">=",
"0.20.0"
]
]
},
{
"name": "shapely",
"specs": [
[
"!=",
"2.0.7"
]
]
}
],
"lcname": "dghs-realutils"
}
JSON
