{"id":22677790,"url":"https://github.com/d3x-at/sd-parsers","last_synced_at":"2025-04-13T11:09:38.341Z","repository":{"id":151151301,"uuid":"622682679","full_name":"d3x-at/sd-parsers","owner":"d3x-at","description":"A Python library to read metadata from images created by Stable Diffusion.","archived":false,"fork":false,"pushed_at":"2025-04-03T18:22:13.000Z","size":767,"stargazers_count":33,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-13T11:09:33.663Z","etag":null,"topics":["automatic1111","comfyui","fooocus","invokeai","metadata-extraction","novelai","parse","parser","stable-diffusion","stable-diffusion-library"],"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/d3x-at.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","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}},"created_at":"2023-04-02T20:21:02.000Z","updated_at":"2025-04-03T18:22:17.000Z","dependencies_parsed_at":"2024-06-29T14:38:58.837Z","dependency_job_id":"8d39bc9b-3f7c-44c7-b736-20dd4d49ea50","html_url":"https://github.com/d3x-at/sd-parsers","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d3x-at%2Fsd-parsers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d3x-at%2Fsd-parsers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d3x-at%2Fsd-parsers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d3x-at%2Fsd-parsers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/d3x-at","download_url":"https://codeload.github.com/d3x-at/sd-parsers/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248703199,"owners_count":21148118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["automatic1111","comfyui","fooocus","invokeai","metadata-extraction","novelai","parse","parser","stable-diffusion","stable-diffusion-library"],"created_at":"2024-12-09T18:01:23.524Z","updated_at":"2025-04-13T11:09:38.335Z","avatar_url":"https://github.com/d3x-at.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SD-Parsers\nRead structured metadata from images created with stable diffusion.\n\n![Example Output](example_output.png)\n\n## Features\n\nPrompts as well as some well-known generation parameters are provided as easily accessible properties (see [Output](#output)).\n\nSupports reading metadata from images generated with:\n* Automatic1111's Stable Diffusion web UI\n* ComfyUI *\n* Fooocus\n* InvokeAI\n* NovelAI\n\n\\* Custom ComfyUI nodes might parse incorrectly / with incomplete data.\n\n## Installation\n```\npip install sd-parsers\n```\n\n## Usage\n\nFrom command line: ```python3 -m sd_parsers \u003cfilenames\u003e```\n\n\n### Basic usage:\n\nFor a simple query, import ```ParserManager``` from ```sd_parsers``` and use its ```parse()``` method to parse an image. (see [examples](examples))\n\n#### Read prompt information from a given filename with `parse()`:\n```python\nfrom sd_parsers import ParserManager\n\nparser_manager = ParserManager()\n\ndef main():\n    prompt_info = parser_manager.parse(\"image.png\")\n\n    if prompt_info:\n        for prompt in prompt_info.prompts:\n            print(f\"Prompt: {prompt.value}\")\n```\n\n#### Read prompt information from an already opened image:\n```python\nfrom PIL import Image\nfrom sd_parsers import ParserManager\n\nparser_manager = ParserManager()\n\ndef main():\n    with Image.open('image.png') as image:\n        prompt_info = parser_manager.parse(image)\n```\n\n### Parsing options:\n\n#### Configure metadata extraction:\n```python\nfrom sd_parsers import ParserManager, Eagerness\n\nparser_manager = ParserManager(eagerness=Eagerness.EAGER)\n```\n\n`Eagerness` sets the metadata searching effort\n\nThe given eagerness level is the highest that will be considered. \n\ni.e.: With `Eagerness.DEFAULT` set, the ParserManager will try `FAST` followed by `DEFAULT`.\n\nFor now, this only has an effect on PNG images:\n- **FAST**: cut some corners to save some time\n\n  This only looks at Image.info.\n\n- **DEFAULT**: try to ensure all metadata is read\n\n  This will also look at Image.text, reading the whole image data to do so.\n\n- **EAGER**: include additional methods to try and retrieve metadata\n\n  Includes the [stenographic alpha](src/sd_parsers/extractors/_png_stenographic_alpha.py) extractor, which will look for hidden metadata. (computationally expensive!)\n\n\n#### Only use specific (or custom) parser modules:\n\n```python\nfrom sd_parsers import ParserManager\nfrom sd_parsers.data import PromptInfo, Sampler\nfrom sd_parsers.parsers import Parser, AUTOMATIC1111Parser\n\n# basic implementation of a parser class\n# see parsers/_dummy_parser.py for a more detailed explanation\nclass DummyParser(Parser):\n    def parse(self, parameters):\n        return PromptInfo(\n            generator=self.generator,\n            samplers=[Sampler(name=\"dummy_sampler\", parameters={})],\n            metadata={\"some other\": \"metadata\"},\n            raw_parameters=parameters,\n        )\n\n# you can use multiple manager instances using different parsers\n# caution: the order of parser entries matters!\n# here, the DummyParser will ignore its input and always return a result,\n# resulting in the AUTOMATIC1111 parser to never be used\nparser_manager = ParserManager(managed_parsers=[DummyParser, AUTOMATIC1111Parser])\n```\n\n#### Change default parser modules:\n\n```python\nfrom sd_parsers import ParserManager\nfrom sd_parsers.parsers import MANAGED_PARSERS, AUTOMATIC1111Parser\n\n# remove all preset parser modules\nMANAGED_PARSERS.clear()\n\n# add the AUTOMATIC1111 parser as only parser module\nMANAGED_PARSERS.extend([AUTOMATIC1111Parser])\n\n# the default will still be overriden with managed_parsers=...\nparser_manager = ParserManager()\n```\n\n#### Add or change metadata extractors:\n\n```python\nfrom PIL.Image import Image\nfrom sd_parsers import ParserManager, Eagerness\nfrom sd_parsers.data import Generators\nfrom sd_parsers.extractors import METADATA_EXTRACTORS\n\n# define a custom extractor\ndef custom_extractor(i: Image, g: Generators):\n    return {\"parameters\": \"custom extracted data\\nSampler: UniPC, Steps: 15, CFG scale: 5\"}\n\n# remove all preset PNG extractors for the first (FAST) stage\nMETADATA_EXTRACTORS[\"PNG\"][Eagerness.FAST].clear()\n\n# add custom extractor\nMETADATA_EXTRACTORS[\"PNG\"][Eagerness.FAST].append(custom_extractor)\n\nparser_manager = ParserManager()\n```\n\n### Output\nThe `parse()` method returns a `PromptInfo` ([source](src/sd_parsers/data/prompt_info.py)) object when suitable metadata is found.\n\n\u003e Use ```python3 -m sd_parsers \u003cimage.png\u003e``` to get an idea of the data parsed from an image file.\n\n\u003e To get a result in JSON form, an approach as demonstrated in https://github.com/d3x-at/sd-parsers-web can be used.\n\n`PromptInfo` contains the following properties :\n* `generator`: Specifies the image [generator](src/sd_parsers/data/generators.py) that may have been used for creating the image.\n\n* `full_prompt`: A full prompt, if present in the image metadata.\n\n  Otherwise, a simple concatenation of all prompts found.\n\n* `full_negative_prompt`: A full negative prompt if present in the image metadata. \n  \n  Otherwise, a simple concatenation of all negative prompts found.\n\n* `prompts`: All [prompts](src/sd_parsers/data/prompt.py) found in the parsed metadata.\n\n* `negative_prompts`: All negative [prompts](src/sd_parsers/data/prompt.py) found in the parsed metadata.\n\n* `models`: [Models](src/sd_parsers/data/model.py) used in the image generation process.\n\n* `samplers`: [Samplers](src/sd_parsers/data/sampler.py) used in the image generation process.\n\n  A Sampler contains the following properties specific to itself:\n    * `name`: The name of the sampler\n\n    * `parameters`: Generation parameters, including _cfg_scale_, _seed_, _steps_ and others.\n\n    * `sampler_id`: A unique id of the sampler (if present in the metadata)\n\n    * `model`: The model used by this sampler.\n\n    * `prompts`: A list of positive prompts used by this sampler.\n    \n    * `negative_prompts`: A list of negative prompts used by this sampler.\n\n* `metadata`: Additional metadata which could not be attributed to one of the former described.\n\n  Highly dependent on the provided data structure of the respective image generator.\n\n* `raw_parameters`: The unprocessed metadata entries as found in the parsed image (if present).\n\n## Contributing\nAs i don't have the time and resources to keep up with all the available AI-based image generators out there, the scale and features of this library is depending greatly on your help.\n\nIf you find the sd-parsers library unable to read metadata from an image, feel free to open an [issue](https://github.com/d3x-at/sd-parsers/issues).\n\nSee [CONTRIBUTING.md](https://github.com/d3x-at/sd-parsers/blob/master/.github/CONTRIBUTING.md), if you are willing to help with improving the library itself and/or to create/maintain an additional parser module.\n\n\n## Credits\nIdea and motivation using AUTOMATIC1111's stable diffusion webui\n- https://github.com/AUTOMATIC1111/stable-diffusion-webui\n\nExample workflows for testing the ComfyUI parser\n- https://github.com/comfyanonymous/ComfyUI_examples\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd3x-at%2Fsd-parsers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd3x-at%2Fsd-parsers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd3x-at%2Fsd-parsers/lists"}