imagefv-extractor 1.0.0__tar.gz

imagefv_extractor-1.0.0/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

imagefv_extractor-1.0.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: imagefv-extractor
+Version: 1.0.0
+Summary: Extract bootloader and charging images from imagefv firmware blobs
+Author-email: chkndrp <chkndrp@gmail.com>
+License-Expression: LGPL-3.0
+Project-URL: Repository, https://github.com/chkndrp/imagefv-extractor
+Project-URL: Issues, https://github.com/chkndrp/imagefv-extractor/issues
+Project-URL: Changelog, https://github.com/chkndrp/imagefv-extractor/blob/master/CHANGELOG.md
+Project-URL: Homepage, https://github.com/chkndrp/imagefv-extractor/blob/master/README.md
+Keywords: android,firmware,imagefv,qcom,qualcomm,uefi,extractor,bootloader
+Classifier: Programming Language :: Python :: 3
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Environment :: Console
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: uefi_firmware==1.16
+Provides-Extra: dev
+Requires-Dist: pylint>=4.1.3; extra == "dev"
+Dynamic: license-file
+
+# imagefv-extractor
+![PyPI - Version](https://img.shields.io/pypi/v/imagefv-extractor?logo=python&logoColor=white) ![PyPI - Downloads](https://img.shields.io/pypi/dm/imagefv-extractor?logo=python&logoColor=white) ![PyPI - Typing](https://img.shields.io/pypi/types/imagefv-extractor?logo=python&logoColor=white)
+
+Extract bootloader/charging pictures from `imagefv` blobs
+
+---
+
+## Install
+```shell
+# With PyPi (recommended)
+pip install fastboot_oem_extractor
+```
+
+```shell
+# When running from source/clone
+pip install -r requirements.txt
+```
+
+---
+
+## Using as a CLI tool:
+```
+usage: extractor.py [-h] [-o OUTPUT] [-v] input [input ...]
+
+Extract bootloader/charging pictures from imagefv blobs
+
+positional arguments:
+  input                Input file(s) to process
+
+options:
+  -h, --help           show this help message and exit
+  -o, --output OUTPUT  Output directory (default: extracted_images)
+  -v, --verbose        Enable verbose logging (default: False)
+```
+
+1. Prepare an `imagefv` blob from firmware or pull it from a device via `adb`, then run:
+2. Run the CLI against the image
+
+```shell
+# PyPi
+python -m imagefv_extractor ./imagefv.bin
+```
+
+```shell
+# Source/clone
+python ./extractor.py ./imagefv.bin
+```
+
+---
+
+## Using as a Python library
+
+This project can also be used as a library for other tools that want to integrate this.
+There is one public function:
+
+```python
+extract_images(firmware_file, output_dir="extracted_images") -> dict[str, str]
+```
+
+- `firmware_file` (`str | pathlib.Path`): Path to the imagefv firmware image.
+- `output_dir` (`str | pathlib.Path`): Directory where extracted files will be written. Defaults to `"extracted_images"`.
+- **Returns:**
+    - A mapping of extracted image labels to their output paths.
+    - An empty mapping if the input is unrecognized or no images are extracted.
+- **Raises:** `OSError` if the output directory cannot be created.
+
+**Quick example:**
+```python
+# from pathlib import Path
+from imagefv_extractor import extract_images
+
+# extracted = extract_images(
+#     Path("./imagefv.elf"),
+#     output_dir=Path("./extracted_images"),
+# )
+
+extracted = extract_images(
+    "./imagefv.elf",
+    output_dir="./extracted_images",
+)
+
+for label, path in extracted.items():
+    print(f"{label}: {path}")
+    # Example output:
+    # logo.img_raw: extracted_images/logo.img/logo.img
+    # logo.img_archive_0: extracted_images/logo.img/images/archive_0000.bmp
+    # ...
+```
+
+## How it works:
+1. The script scans the input file for `UEFI` structures using the `uefi-firmware` package
+2. If it finds them, it dumps all files/sections to a temporary directory
+3. Then it identifies the dumped files for known types (defined in `magic_map` struct) and organizes them
+4. And also if found, any files containing GZip archives (most commonly `logo.img`) are extracted
+
+## Is it possible to repackage it, and create custom splashes?
+During investigation, i have noticed the `imagefv` blob contains some CoT certificates, 
+so it is absolutely possible that this partition is verified during the `XBL` phase,
+causing the device not to boot if it is altered.
+
+```
+DECIMAL       HEXADECIMAL     DESCRIPTION
+--------------------------------------------------------------------------------
+0             0x0             ELF, 32-bit LSB executable, ARM, version 1 (SYSV)
+4096          0x1000          UEFI PI Firmware Volume, volume size: 6291456, header size: 0, revision: 0, EFI Firmware File System v2, GUID: 8C8CE578-8A3D-4F1C-3599-896185C32DD3
+4216          0x1078          LZMA compressed data, properties: 0x5D, dictionary size: 16777216 bytes, uncompressed size: 7237640 bytes
+6296088       0x601218        Certificate in DER format (x509 v3), header length: 4, sequence length: 596
+6296688       0x601470        Certificate in DER format (x509 v3), header length: 4, sequence length: 685
+6297377       0x601721        Certificate in DER format (x509 v3), header length: 4, sequence length: 720
+```
+
+I also couldn't find any open-source (re)packaging tools for it either, so one would need to be created. However i'm not risking a hard-brick.
+
+Here are some references to it being loaded on `xiaomi-amethyst` during `ABL` phase:
+```
+GetAdjustLogoIndexpDisplayInfo->uDisplayWidth 1220: 2712, country_info = 1, uLogoIndex = 0, realLogoIndex = 128!
+Display_Utils_RenderSplashScreen: load imagefv name is: logo.img
+LoadCompressedImageFromLogoData: Setvariable Logo Image returned eStatus: Success, LogoMagic: LOGO!!!
+LoadCompressedImageFromLogoData: LogoCompressedBlockNum:9 LogoCompressedBytesNum:35458 
+Display_Utils_RenderSplashScreen: CompressedData size is: 35458 logo index = 128
+DeCompressLogoData: DecompressBufferSize:9925976  ScratchSize:131072
+DeCompressLogoData: logo decompress done, use time: 19ms
+Display_Utils_RenderSplashScreen: OEM Logo Successfully Loaded
+```
+
+## Requirements
+- Python 3.10 or newer
+- Installed `uefi_firmware` pip package

imagefv_extractor-1.0.0/README.md

@@ -0,0 +1,128 @@
+# imagefv-extractor
+![PyPI - Version](https://img.shields.io/pypi/v/imagefv-extractor?logo=python&logoColor=white) ![PyPI - Downloads](https://img.shields.io/pypi/dm/imagefv-extractor?logo=python&logoColor=white) ![PyPI - Typing](https://img.shields.io/pypi/types/imagefv-extractor?logo=python&logoColor=white)
+
+Extract bootloader/charging pictures from `imagefv` blobs
+
+---
+
+## Install
+```shell
+# With PyPi (recommended)
+pip install fastboot_oem_extractor
+```
+
+```shell
+# When running from source/clone
+pip install -r requirements.txt
+```
+
+---
+
+## Using as a CLI tool:
+```
+usage: extractor.py [-h] [-o OUTPUT] [-v] input [input ...]
+
+Extract bootloader/charging pictures from imagefv blobs
+
+positional arguments:
+  input                Input file(s) to process
+
+options:
+  -h, --help           show this help message and exit
+  -o, --output OUTPUT  Output directory (default: extracted_images)
+  -v, --verbose        Enable verbose logging (default: False)
+```
+
+1. Prepare an `imagefv` blob from firmware or pull it from a device via `adb`, then run:
+2. Run the CLI against the image
+
+```shell
+# PyPi
+python -m imagefv_extractor ./imagefv.bin
+```
+
+```shell
+# Source/clone
+python ./extractor.py ./imagefv.bin
+```
+
+---
+
+## Using as a Python library
+
+This project can also be used as a library for other tools that want to integrate this.
+There is one public function:
+
+```python
+extract_images(firmware_file, output_dir="extracted_images") -> dict[str, str]
+```
+
+- `firmware_file` (`str | pathlib.Path`): Path to the imagefv firmware image.
+- `output_dir` (`str | pathlib.Path`): Directory where extracted files will be written. Defaults to `"extracted_images"`.
+- **Returns:**
+    - A mapping of extracted image labels to their output paths.
+    - An empty mapping if the input is unrecognized or no images are extracted.
+- **Raises:** `OSError` if the output directory cannot be created.
+
+**Quick example:**
+```python
+# from pathlib import Path
+from imagefv_extractor import extract_images
+
+# extracted = extract_images(
+#     Path("./imagefv.elf"),
+#     output_dir=Path("./extracted_images"),
+# )
+
+extracted = extract_images(
+    "./imagefv.elf",
+    output_dir="./extracted_images",
+)
+
+for label, path in extracted.items():
+    print(f"{label}: {path}")
+    # Example output:
+    # logo.img_raw: extracted_images/logo.img/logo.img
+    # logo.img_archive_0: extracted_images/logo.img/images/archive_0000.bmp
+    # ...
+```
+
+## How it works:
+1. The script scans the input file for `UEFI` structures using the `uefi-firmware` package
+2. If it finds them, it dumps all files/sections to a temporary directory
+3. Then it identifies the dumped files for known types (defined in `magic_map` struct) and organizes them
+4. And also if found, any files containing GZip archives (most commonly `logo.img`) are extracted
+
+## Is it possible to repackage it, and create custom splashes?
+During investigation, i have noticed the `imagefv` blob contains some CoT certificates, 
+so it is absolutely possible that this partition is verified during the `XBL` phase,
+causing the device not to boot if it is altered.
+
+```
+DECIMAL       HEXADECIMAL     DESCRIPTION
+--------------------------------------------------------------------------------
+0             0x0             ELF, 32-bit LSB executable, ARM, version 1 (SYSV)
+4096          0x1000          UEFI PI Firmware Volume, volume size: 6291456, header size: 0, revision: 0, EFI Firmware File System v2, GUID: 8C8CE578-8A3D-4F1C-3599-896185C32DD3
+4216          0x1078          LZMA compressed data, properties: 0x5D, dictionary size: 16777216 bytes, uncompressed size: 7237640 bytes
+6296088       0x601218        Certificate in DER format (x509 v3), header length: 4, sequence length: 596
+6296688       0x601470        Certificate in DER format (x509 v3), header length: 4, sequence length: 685
+6297377       0x601721        Certificate in DER format (x509 v3), header length: 4, sequence length: 720
+```
+
+I also couldn't find any open-source (re)packaging tools for it either, so one would need to be created. However i'm not risking a hard-brick.
+
+Here are some references to it being loaded on `xiaomi-amethyst` during `ABL` phase:
+```
+GetAdjustLogoIndexpDisplayInfo->uDisplayWidth 1220: 2712, country_info = 1, uLogoIndex = 0, realLogoIndex = 128!
+Display_Utils_RenderSplashScreen: load imagefv name is: logo.img
+LoadCompressedImageFromLogoData: Setvariable Logo Image returned eStatus: Success, LogoMagic: LOGO!!!
+LoadCompressedImageFromLogoData: LogoCompressedBlockNum:9 LogoCompressedBytesNum:35458 
+Display_Utils_RenderSplashScreen: CompressedData size is: 35458 logo index = 128
+DeCompressLogoData: DecompressBufferSize:9925976  ScratchSize:131072
+DeCompressLogoData: logo decompress done, use time: 19ms
+Display_Utils_RenderSplashScreen: OEM Logo Successfully Loaded
+```
+
+## Requirements
+- Python 3.10 or newer
+- Installed `uefi_firmware` pip package

imagefv_extractor-1.0.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["setuptools>=77.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "imagefv-extractor"
+version = "1.0.0"
+description = "Extract bootloader and charging images from imagefv firmware blobs"
+authors = [{ name = "chkndrp", email = "chkndrp@gmail.com" }]
+keywords = [
+    "android", "firmware", "imagefv", "qcom", "qualcomm",
+    "uefi", "extractor", "bootloader",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+    "Environment :: Console",
+    "Typing :: Typed",
+]
+dependencies = [
+    "uefi_firmware==1.16"
+]
+license = "LGPL-3.0"
+readme = "README.md"
+requires-python = ">=3.10"
+
+[project.urls]
+Repository = "https://github.com/chkndrp/imagefv-extractor"
+Issues     = "https://github.com/chkndrp/imagefv-extractor/issues"
+Changelog  = "https://github.com/chkndrp/imagefv-extractor/blob/master/CHANGELOG.md"
+Homepage = "https://github.com/chkndrp/imagefv-extractor/blob/master/README.md"
+
+[project.scripts]
+imagefv-extractor = "imagefv_extractor.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pylint>=4.1.3",
+]
+
+[tool.pylint.main]
+py-version="3.10"
+clear-cache-post-run = false
+persistent = true
+source-roots = ["src"]
+load-plugins = [
+    "pylint.extensions.check_elif",
+    "pylint.extensions.for_any_all",
+    "pylint.extensions.set_membership",
+    "pylint.extensions.overlapping_exceptions",
+    "pylint.extensions.typing",
+    "pylint.extensions.comparison_placement"
+]
+
+[tool.pylint.classes]
+check-protected-access-in-special-methods = true
+
+[tool.pylint.format]
+expected-line-ending-format = "LF"
+ignore-long-lines = "^\\s*(# )?<?https?://\\S+>?$"
+max-line-length = 110
+
+[tool.pylint.string]
+check-quote-consistency = true
+check-str-concat-over-line-jumps = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["imagefv_extractor*"]
+
+[tool.setuptools.package-data]
+imagefv_extractor = ["py.typed"]

imagefv_extractor-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

imagefv_extractor-1.0.0/src/imagefv_extractor/__init__.py

@@ -0,0 +1,18 @@
+"""Extract bootloader and charging images from imagefv firmware blobs"""
+
+# Extract bootloader/charging pictures from imagefv blobs
+# Copyright (C) 2026 chkndrp
+#
+# This library is free software; you can redistribute it and/or modify it
+# under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+
+from .extract import extract_images
+
+__all__ = ["extract_images"]

imagefv_extractor-1.0.0/src/imagefv_extractor/__main__.py

@@ -0,0 +1,19 @@
+"""Extract bootloader and charging images from imagefv firmware blobs"""
+
+# Extract bootloader/charging pictures from imagefv blobs
+# Copyright (C) 2026 chkndrp
+#
+# This library is free software; you can redistribute it and/or modify it
+# under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

imagefv_extractor-1.0.0/src/imagefv_extractor/cli.py

@@ -0,0 +1,93 @@
+"""CLI interface"""
+
+# Extract bootloader/charging pictures from imagefv blobs
+# Copyright (C) 2026 chkndrp
+#
+# This library is free software; you can redistribute it and/or modify it
+# under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+
+import argparse
+import logging
+
+from collections.abc import Sequence
+from pathlib import Path
+from .extract import extract_images
+
+logger = logging.getLogger("imagefv-extractor")
+
+
+class _PrefixFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        return f"(x) {super().format(record)}"
+
+
+def _configure_logging(verbose: bool) -> None:
+    logger.setLevel(logging.DEBUG if verbose else logging.INFO)
+    logger.propagate = False
+
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(_PrefixFormatter("%(message)s"))
+        logger.addHandler(handler)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """CLI main entry"""
+
+    parser = argparse.ArgumentParser(
+        description="Extract bootloader/charging pictures from imagefv blobs",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "input",
+        nargs="+",
+        help="Input file(s) to process"
+    )
+    parser.add_argument(
+        "-o", "--output",
+        default="extracted_images",
+        help="Output directory",
+    )
+    parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Enable verbose logging",
+    )
+    args = parser.parse_args(argv)
+
+    _configure_logging(args.verbose)
+
+    failed = False
+    for input_file in args.input:
+        logger.info("Processing: %s", input_file)
+        logger.info("Output directory: %s", args.output)
+
+        output_dir = Path(args.output)
+        if len(args.input) > 1:
+            output_dir /= Path(input_file).stem
+
+        try:
+            extracted_files = extract_images(input_file, output_dir)
+        except OSError as error:
+            logger.error("Could not prepare output for %s: %s", input_file, error)
+            failed = True
+            continue
+
+        if extracted_files:
+            logger.info(
+                "Successfully extracted %d item(s)",
+                len(extracted_files),
+            )
+        else:
+            logger.error("Failed to extract images from %s", input_file)
+            failed = True
+
+    logger.info("Extraction complete!")
+    return int(failed)

imagefv_extractor-1.0.0/src/imagefv_extractor/extract.py

@@ -0,0 +1,348 @@
+"""Main entry"""
+
+# Extract bootloader/charging pictures from imagefv blobs
+# Copyright (C) 2026 chkndrp
+#
+# This library is free software; you can redistribute it and/or modify it
+# under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+
+import contextlib
+import gzip
+import tempfile
+import shutil
+import logging
+import io
+
+from pathlib import Path
+from uefi_firmware.uefi import FirmwareVolume
+from uefi_firmware.utils import search_firmware_volumes
+
+logger = logging.getLogger("imagefv-extractor")
+
+
+def _get_file_extension(header: bytes) -> str:
+    """Determine file extension from magic bytes"""
+
+    magic_map = {
+        b"\x7fELF": "elf",
+        b"\x1f\x8b": "gz",
+        b"BM": "bmp",
+        b"\x89PNG": "png",
+        b"GIF": "gif",
+        b"PK\x03\x04": "zip",
+        b"BZh": "bz2",
+        b"<?xml": "xml",
+        b"<": "xml",
+    }
+
+    for magic, ext in magic_map.items():
+        if header.startswith(magic):
+            return ext
+
+    if header[:4] in {b"\xff\xd8\xff\xe0", b"\xff\xd8\xff\xe1"}:
+        return "jpg"
+
+    return "bin"
+
+
+def _extract_gzip_stream(data: bytes, output_path: Path) -> bool:
+    """Extract gzip data efficiently"""
+
+    try:
+        with gzip.GzipFile(fileobj=io.BytesIO(data)) as gzfile:
+            with open(output_path, "wb") as out:
+                shutil.copyfileobj(gzfile, out, length=1024*1024)
+
+        return True
+    except OSError as e:
+        logger.warning("Failed to decompress gzip: %s", e)
+        return False
+
+
+def _extract_gzip_bounded(data: bytes, start_offset: int,
+        next_offset: int | None, output_path: Path) -> bool:
+    """Extract single gzip stream bounded by next gzip header"""
+
+    try:
+        gzip_data = data[start_offset:next_offset] if next_offset else data[start_offset:]
+
+        with gzip.GzipFile(fileobj=io.BytesIO(gzip_data)) as gzfile:
+            extracted = gzfile.read()
+
+        if extracted:
+            with open(output_path, "wb") as out:
+                out.write(extracted)
+
+            return True
+    except (OSError, EOFError) as e:
+        logger.debug("Failed to extract gzip at offset 0x%x: %s", start_offset, e)
+
+    return False
+
+
+def _extract_and_rename_archive(section_data: bytes, offset: int,
+        next_offset: int | None, output_path: Path, idx: int) -> str | None:
+    """Extract and rename archive with proper extension"""
+
+    if not _extract_gzip_bounded(section_data, offset, next_offset, output_path):
+        return None
+
+    try:
+        size = output_path.stat().st_size
+
+        with open(output_path, "rb") as archive_file:
+            header = archive_file.read(4)
+
+        ext = _get_file_extension(header)
+        better_path = output_path.parent / f"archive_{idx:04d}.{ext}"
+        output_path.rename(better_path)
+
+        logger.info(
+            "Extracted archive %3d at offset 0x%08x -> %s (%.1f MB)",
+            idx,
+            offset,
+            better_path.name,
+            size / 1024 / 1024,
+        )
+        return str(better_path)
+    except OSError as e:
+        logger.error("Failed to rename archive at offset 0x%x: %s", offset, e)
+        return None
+
+
+def _find_gzip_offsets(data: bytes) -> list[int]:
+    """Find all gzip stream offsets by scanning for magic bytes"""
+
+    return [
+        offset
+        for offset in range(len(data) - 1)
+        if data[offset:offset + 2] == b"\x1f\x8b"
+    ]
+
+
+def _extract_file_label(parent_dir: Path) -> str | None:
+    """Extract file label from UI section if available"""
+
+    ui_file = parent_dir / "section0.ui"
+    if not ui_file.exists():
+        return None
+
+    try:
+        with open(ui_file, "rb") as ui_data_file:
+            ui_data = ui_data_file.read()
+
+        if len(ui_data) > 2:
+            decoded = ui_data.decode("utf-16-le", errors="ignore")
+            file_label = decoded.split("\x00")[0].strip()
+
+            if file_label and len(file_label) > 1:
+                return file_label
+
+    except (OSError, UnicodeDecodeError) as e:
+        logger.debug("Could not extract label from %s: %s", ui_file, e)
+
+    return None
+
+
+def _process_large_binary_section(file_label: str, section_data: bytes,
+        output_subdir: Path, extracted_files: dict[str, str]) -> int:
+    """Process large binary sections with multiple gzip archives"""
+
+    raw_path = output_subdir / file_label
+    output_subdir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        with open(raw_path, "wb") as section_file:
+            section_file.write(section_data)
+
+        logger.info("Saved: %s (%d bytes)", file_label, len(section_data))
+        extracted_files[f"{file_label}_raw"] = str(raw_path)
+    except OSError as e:
+        logger.error("Failed to save %s: %s", file_label, e)
+        return 0
+
+    gzip_offsets = _find_gzip_offsets(section_data)
+    logger.info("Found %d gzip stream(s) in %s", len(gzip_offsets), file_label)
+
+    if not gzip_offsets:
+        return 0
+
+    archives_dir = output_subdir / "images"
+    archives_dir.mkdir(parents=True, exist_ok=True)
+
+    extracted_count = 0
+    for idx, offset in enumerate(gzip_offsets):
+        next_offset = gzip_offsets[idx + 1] if idx + 1 < len(gzip_offsets) else None
+        output_path = archives_dir / f"archive_{idx:04d}.bin"
+        extracted_path = _extract_and_rename_archive(
+            section_data,
+            offset,
+            next_offset,
+            output_path,
+            idx,
+        )
+        if not extracted_path:
+            logger.debug("Could not extract gzip at offset 0x%x", offset)
+        else:
+            extracted_files[f"{file_label}_archive_{idx}"] = extracted_path
+            extracted_count += 1
+
+    logger.info("Successfully extracted %d archive(s) from %s", extracted_count, file_label)
+    return extracted_count
+
+
+def _extract_from_section(file_label: str, section_data: bytes, output_subdir: Path,
+        output_dir: Path, extracted_files: dict[str, str]) -> str | None:
+    """Extract images from firmware file section"""
+
+    if file_label.endswith(".bmp") or len(section_data) < 1024*1024:
+        output_path = output_dir / file_label
+        try:
+            with open(output_path, "wb") as output_file:
+                output_file.write(section_data)
+
+            logger.info("Extracted: %s (%d bytes)", file_label, len(section_data))
+            return str(output_path)
+        except OSError as e:
+            logger.error("Failed to save %s: %s", file_label, e)
+            return None
+
+    output_subdir.mkdir(parents=True, exist_ok=True)
+
+    if len(section_data) >= 2 and section_data[0:2] == b"\x1f\x8b":
+        extracted_path = output_subdir / f"{file_label}.extracted"
+
+        logger.info("Detected gzip compression in %s", file_label)
+
+        if _extract_gzip_stream(section_data, extracted_path):
+            size = extracted_path.stat().st_size
+            logger.info("Extracted: %s (gzip) -> %s (%d bytes)", file_label, extracted_path.name, size)
+            return str(extracted_path)
+
+    if len(section_data) > 1024*1024:
+        gzip_offsets = _find_gzip_offsets(section_data)
+
+        if len(gzip_offsets) > 1:
+            logger.info("Detected multiple gzip streams in %s, extracting all...", file_label)
+            _process_large_binary_section(file_label, section_data, output_subdir, extracted_files)
+            return str(output_subdir / file_label)
+
+    output_path = output_subdir / file_label
+    try:
+        with open(output_path, "wb") as output_file:
+            output_file.write(section_data)
+
+        logger.info("Extracted: %s (raw) (%d bytes)", file_label, len(section_data))
+        return str(output_path)
+    except OSError as e:
+        logger.error("Failed to save %s: %s", file_label, e)
+        return None
+
+
+def _process_raw_files(dump_dir: Path, output_dir: Path, extracted_files: dict[str, str]) -> None:
+    """Find and process .raw files from dump directory"""
+
+    for raw_file in dump_dir.rglob("*.raw"):
+        try:
+            parent_dir = raw_file.parent.name
+
+            if not parent_dir.startswith("file-"):
+                continue
+
+            file_label = _extract_file_label(raw_file.parent)
+
+            if not file_label or len(file_label) <= 1:
+                file_label = parent_dir[5:].lower()
+
+            with open(raw_file, "rb") as raw_data_file:
+                section_data = raw_data_file.read()
+
+            output_subdir = output_dir / file_label
+            extracted = _extract_from_section(
+                file_label,
+                section_data,
+                output_subdir,
+                output_dir,
+                extracted_files,
+            )
+
+            if extracted:
+                extracted_files[file_label] = extracted
+        except OSError as e:
+            logger.warning("Error processing %s: %s", raw_file, e)
+
+
+def extract_images(firmware_file: str | Path, output_dir: str | Path = "extracted_images") -> dict[str, str]:
+    """
+    Extract images from a firmware file and return their labels and paths
+
+    :param firmware_file: Path to the imagefv firmware image
+    :type firmware_file: str | pathlib.Path
+
+    :param output_dir: Directory where extracted files will be written
+    :type output_dir: str | pathlib.Path
+
+    :returns: A mapping from extracted image labels to output paths. The mapping is
+        empty when no images were extracted
+    :rtype: dict[str, str]
+    :raises OSError: If the output directory cannot be created
+    """
+
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    extracted_files: dict[str, str] = {}
+    firmware_file = Path(firmware_file)
+
+    if not firmware_file.exists():
+        logger.error("File not found: %s", firmware_file)
+        return extracted_files
+
+    try:
+        with firmware_file.open("rb") as elf_data_file:
+            data = elf_data_file.read()
+
+        volumes = search_firmware_volumes(data)
+
+        if not volumes:
+            logger.error("No UEFI firmware volumes found in file")
+            return extracted_files
+
+        logger.info("Found %d firmware volume(s)", len(volumes))
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmpdir_path = Path(tmpdir)
+
+            for offset in volumes:
+                logger.info("Processing FV at offset: 0x%x", offset)
+                try:
+                    fv = FirmwareVolume(
+                        data[offset-40:],
+                        name=f"0x{offset-40:x}"
+                    )
+
+                    if fv.valid_header:
+                        logger.info("FV Size: %d bytes", fv.size)
+
+                        if fv.process():
+                            logger.info("FV processed successfully, dumping files...")
+                            with contextlib.redirect_stdout(io.StringIO()):
+                                fv.dump(str(tmpdir_path))
+                            _process_raw_files(tmpdir_path, output_dir, extracted_files)
+                        else:
+                            logger.warning("Failed to process FV at 0x%x", offset)
+                    else:
+                        logger.debug("Invalid FV header at offset 0x%x", offset)
+                except OSError as e:
+                    logger.warning("Error processing FV at offset 0x%x: %s", offset, e)
+
+    except OSError as e:
+        logger.error("Error processing ELF: %s", e)
+
+    return extracted_files

imagefv_extractor-1.0.0/src/imagefv_extractor.egg-info/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: imagefv-extractor
+Version: 1.0.0
+Summary: Extract bootloader and charging images from imagefv firmware blobs
+Author-email: chkndrp <chkndrp@gmail.com>
+License-Expression: LGPL-3.0
+Project-URL: Repository, https://github.com/chkndrp/imagefv-extractor
+Project-URL: Issues, https://github.com/chkndrp/imagefv-extractor/issues
+Project-URL: Changelog, https://github.com/chkndrp/imagefv-extractor/blob/master/CHANGELOG.md
+Project-URL: Homepage, https://github.com/chkndrp/imagefv-extractor/blob/master/README.md
+Keywords: android,firmware,imagefv,qcom,qualcomm,uefi,extractor,bootloader
+Classifier: Programming Language :: Python :: 3
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Environment :: Console
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: uefi_firmware==1.16
+Provides-Extra: dev
+Requires-Dist: pylint>=4.1.3; extra == "dev"
+Dynamic: license-file
+
+# imagefv-extractor
+![PyPI - Version](https://img.shields.io/pypi/v/imagefv-extractor?logo=python&logoColor=white) ![PyPI - Downloads](https://img.shields.io/pypi/dm/imagefv-extractor?logo=python&logoColor=white) ![PyPI - Typing](https://img.shields.io/pypi/types/imagefv-extractor?logo=python&logoColor=white)
+
+Extract bootloader/charging pictures from `imagefv` blobs
+
+---
+
+## Install
+```shell
+# With PyPi (recommended)
+pip install fastboot_oem_extractor
+```
+
+```shell
+# When running from source/clone
+pip install -r requirements.txt
+```
+
+---
+
+## Using as a CLI tool:
+```
+usage: extractor.py [-h] [-o OUTPUT] [-v] input [input ...]
+
+Extract bootloader/charging pictures from imagefv blobs
+
+positional arguments:
+  input                Input file(s) to process
+
+options:
+  -h, --help           show this help message and exit
+  -o, --output OUTPUT  Output directory (default: extracted_images)
+  -v, --verbose        Enable verbose logging (default: False)
+```
+
+1. Prepare an `imagefv` blob from firmware or pull it from a device via `adb`, then run:
+2. Run the CLI against the image
+
+```shell
+# PyPi
+python -m imagefv_extractor ./imagefv.bin
+```
+
+```shell
+# Source/clone
+python ./extractor.py ./imagefv.bin
+```
+
+---
+
+## Using as a Python library
+
+This project can also be used as a library for other tools that want to integrate this.
+There is one public function:
+
+```python
+extract_images(firmware_file, output_dir="extracted_images") -> dict[str, str]
+```
+
+- `firmware_file` (`str | pathlib.Path`): Path to the imagefv firmware image.
+- `output_dir` (`str | pathlib.Path`): Directory where extracted files will be written. Defaults to `"extracted_images"`.
+- **Returns:**
+    - A mapping of extracted image labels to their output paths.
+    - An empty mapping if the input is unrecognized or no images are extracted.
+- **Raises:** `OSError` if the output directory cannot be created.
+
+**Quick example:**
+```python
+# from pathlib import Path
+from imagefv_extractor import extract_images
+
+# extracted = extract_images(
+#     Path("./imagefv.elf"),
+#     output_dir=Path("./extracted_images"),
+# )
+
+extracted = extract_images(
+    "./imagefv.elf",
+    output_dir="./extracted_images",
+)
+
+for label, path in extracted.items():
+    print(f"{label}: {path}")
+    # Example output:
+    # logo.img_raw: extracted_images/logo.img/logo.img
+    # logo.img_archive_0: extracted_images/logo.img/images/archive_0000.bmp
+    # ...
+```
+
+## How it works:
+1. The script scans the input file for `UEFI` structures using the `uefi-firmware` package
+2. If it finds them, it dumps all files/sections to a temporary directory
+3. Then it identifies the dumped files for known types (defined in `magic_map` struct) and organizes them
+4. And also if found, any files containing GZip archives (most commonly `logo.img`) are extracted
+
+## Is it possible to repackage it, and create custom splashes?
+During investigation, i have noticed the `imagefv` blob contains some CoT certificates, 
+so it is absolutely possible that this partition is verified during the `XBL` phase,
+causing the device not to boot if it is altered.
+
+```
+DECIMAL       HEXADECIMAL     DESCRIPTION
+--------------------------------------------------------------------------------
+0             0x0             ELF, 32-bit LSB executable, ARM, version 1 (SYSV)
+4096          0x1000          UEFI PI Firmware Volume, volume size: 6291456, header size: 0, revision: 0, EFI Firmware File System v2, GUID: 8C8CE578-8A3D-4F1C-3599-896185C32DD3
+4216          0x1078          LZMA compressed data, properties: 0x5D, dictionary size: 16777216 bytes, uncompressed size: 7237640 bytes
+6296088       0x601218        Certificate in DER format (x509 v3), header length: 4, sequence length: 596
+6296688       0x601470        Certificate in DER format (x509 v3), header length: 4, sequence length: 685
+6297377       0x601721        Certificate in DER format (x509 v3), header length: 4, sequence length: 720
+```
+
+I also couldn't find any open-source (re)packaging tools for it either, so one would need to be created. However i'm not risking a hard-brick.
+
+Here are some references to it being loaded on `xiaomi-amethyst` during `ABL` phase:
+```
+GetAdjustLogoIndexpDisplayInfo->uDisplayWidth 1220: 2712, country_info = 1, uLogoIndex = 0, realLogoIndex = 128!
+Display_Utils_RenderSplashScreen: load imagefv name is: logo.img
+LoadCompressedImageFromLogoData: Setvariable Logo Image returned eStatus: Success, LogoMagic: LOGO!!!
+LoadCompressedImageFromLogoData: LogoCompressedBlockNum:9 LogoCompressedBytesNum:35458 
+Display_Utils_RenderSplashScreen: CompressedData size is: 35458 logo index = 128
+DeCompressLogoData: DecompressBufferSize:9925976  ScratchSize:131072
+DeCompressLogoData: logo decompress done, use time: 19ms
+Display_Utils_RenderSplashScreen: OEM Logo Successfully Loaded
+```
+
+## Requirements
+- Python 3.10 or newer
+- Installed `uefi_firmware` pip package

imagefv_extractor-1.0.0/src/imagefv_extractor.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/imagefv_extractor/__init__.py
+src/imagefv_extractor/__main__.py
+src/imagefv_extractor/cli.py
+src/imagefv_extractor/extract.py
+src/imagefv_extractor/py.typed
+src/imagefv_extractor.egg-info/PKG-INFO
+src/imagefv_extractor.egg-info/SOURCES.txt
+src/imagefv_extractor.egg-info/dependency_links.txt
+src/imagefv_extractor.egg-info/entry_points.txt
+src/imagefv_extractor.egg-info/requires.txt
+src/imagefv_extractor.egg-info/top_level.txt

imagefv_extractor-1.0.0/src/imagefv_extractor.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

imagefv_extractor-1.0.0/src/imagefv_extractor.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+imagefv-extractor = imagefv_extractor.cli:main

imagefv_extractor-1.0.0/src/imagefv_extractor.egg-info/requires.txt

@@ -0,0 +1,4 @@
+uefi_firmware==1.16
+
+[dev]
+pylint>=4.1.3

imagefv_extractor-1.0.0/src/imagefv_extractor.egg-info/top_level.txt

@@ -0,0 +1 @@
+imagefv_extractor