Skip to main content

This tool allows you to easily convert specified photos and images into EPUB e-book format, making it accessible for family and friends. It can be used to create monthly or yearly photo collections for children and transform travel photos into e-books.

Project description

epub-image-helper

PyPI PyPI Downloads

This tool allows you to easily convert specified photos and images into EPUB e-book format, making it accessible for family and friends. It can be used to create monthly or yearly photo collections for children and transform travel photos into e-books.

Note

% cat requirements.txt 
#EbookLib==0.18
#git+https://github.com/changyy/ebooklib.git@release#egg=EbookLib
#EbookLib @ git+https://github.com/changyy/ebooklib.git@release
EbookLib.changyy==0.18.2023.1221.0
lxml==4.9.3
Pillow==10.1.0
PyMuPDF==1.23.7
PyMuPDFb==1.23.7
six==1.16.0

This tool relies on the Python library EbookLib to create EPUB format files.

However, currently, ebooklib v0.18 still has some features that need enhancement. Pull requests (PRs) have been created and are awaiting review by the original author. In the meantime, an alternative solution has been implemented using the ebooklib.changyy package. Once the required features for the future are integrated, it will be possible to switch back to the original ebooklib.

More info:


Quick test

Convert a PDF file consisting entirely of images to an EPUB file consisting entirely of images

% epub-image-helper | jq -r '.version'
1.0.4
% mkdir /tmp/test-pdf-workdir
% ls /tmp/input.pdf 
/tmp/input.pdf
% python3 -c 'from epub_image_helper.testPdf2Epub import testPdf2Epub ; testPdf2Epub(inputFile="/tmp/input.pdf", outputFile="/tmp/output.epub", tmpWorkDir="/tmp/test-pdf-workdir")'
{
    "status": true,
...
    "output": {
        "path": "/tmp/output.epub",
        "size": 140028568,
        "sizeReadable": "133.54 MB",
        "imageCount": 0,
        "timeCost": [
            3.0279159545898438e-05,
            44.72491812705994,
            2.896683931350708
        ]
    },
    "error": [],
    "version": "1.0.4"
}

Test image compression

% epub-image-helper | jq -r '.version'
1.0.4
% python3 -c 'from epub_image_helper.testImageCompression import testImageCompression; testImageCompression("/tmp/test-images")'
000.png
plan: png, 100: rawSize: 720749, newSize: 720749
plan: png, 95: rawSize: 720749, newSize: 923203
plan: png, 90: rawSize: 720749, newSize: 923203
plan: png, 85: rawSize: 720749, newSize: 923203
plan: jpg, 100: rawSize: 720749, newSize: 3012792
plan: jpg, 95: rawSize: 720749, newSize: 2023737
plan: jpg, 90: rawSize: 720749, newSize: 1557584
plan: jpg, 85: rawSize: 720749, newSize: 1310936
...

Batch processing Usage

% epub-image-helper | jq -r '.version'
1.0.4
% tree  example    
example
├── 01-batch-image-to-epub
│   ├── image2epub.py
│   └── input.json
└── 02-batch-pdf-to-epub
    ├── input.json
    └── pdf2epub.py

3 directories, 4 files

Pack your NAS photo albums

% cd example/01-batch-image-to-epub
% tree .
.
├── epub
├── image2epub.py
├── input.json
└── storage
    └── url
        ├── 001
        │   ├── 01.jpg
        │   ├── 02.jpg
        │   └── 03.jpg
        └── 002
            ├── 01.jpg
            ├── 02.jpg
            ├── 03.jpg
            ├── 04.jpg
            └── 05.jpg

6 directories, 10 files
% cat input.json
[
  { 
    "name": "MyPhotosA",
    "author": ["Author"],
    "books": [
      "https://localhost/001/A", 
      "https://localhost/002/B", 
      "https://localhost/003/C"
    ]
  },
  { 
    "name": "MyPhotosB",
    "author": ["Author"],
    "books": [
      "https://localhost/004/A", 
      "https://localhost/005/B", 
      "https://localhost/006/C"
    ]
  }
]
% python3 image2epub.py
...
% tree epub 
epub
└── MyPhotosA
    ├── MyPhotosA01.epub
    └── MyPhotosA02.epub

2 directories, 2 files

Usage

% pip install epub-image-helper
% epub-image-helper
{
    "status": false,
    "input": {
        "output": "/tmp/test.epub",
        "bookConfig": "{}",
        "bookCover": "",
        "bookId": "20a3f61e-8c83-4fca-9846-afd5ffbf108a",
        "bookTitle": "Unknown",
        "bookAuthor": "Unknown",
        "epubcheck": false,
        "imageDir": [],
        "pickFirstImageToBeBookCover": false,
        "debug": false,
        "bookTableOfContent": [],
        "imageFormatConversionTable": {}
    },
    "output": {
        "path": null,
        "size": 0,
        "sizeReadable": null,
        "imageCount": 0,
        "timeCost": [
            5.9604644775390625e-06
        ]
    },
    "error": [
        "If both 'imageDir' and 'bookTableOfContent' are empty, please set at least one of them."
    ],
    "version": "1.0.0"
}

% epub-image-helper -h
usage: epub-image-helper [-h] [--output OUTPUT] [--bookConfig BOOKCONFIG] [--bookCover BOOKCOVER] [--bookTitle BOOKTITLE]
              [--bookId BOOKID] [--bookAuthor BOOKAUTHOR] [--pickFirstImageToBeBookCover] [--debug]
              [--epubcheck]
              [imageDir ...]

positional arguments:
  imageDir              the directory where the image file is located

options:
  -h, --help            show this help message and exit
  --output OUTPUT       output epub path
  --bookConfig BOOKCONFIG
                        a JSON config for EPUB builder. '@-' will read from stdin
  --bookCover BOOKCOVER
                        set a cover image for EPUB
  --bookTitle BOOKTITLE
                        set book title
  --bookId BOOKID       set book uuid info
  --bookAuthor BOOKAUTHOR
                        set book author info
  --pickFirstImageToBeBookCover
                        Select the first image as the book cover when the 'bookCover' parameter is not specified
  --debug               show bookConfig only
  --epubcheck           test output epub format via epubcheck command

1. From an image folder to an EPUB book

% tree 01-image-folder 
01-image-folder
├── 01.jpg
├── 02.jpg
└── 03.jpg

1 directory, 3 files

% epub-image-helper exmaple/01-image-folder 
{
    "status": true,
    "input": {
        "output": "/tmp/test.epub",
        "bookConfig": "{}",
        "bookCover": "",
        "bookId": "b717c302-b724-40aa-a9bf-dbe885b51bfb",
        "bookTitle": "Unknown",
        "bookAuthor": "Unknown",
        "epubcheck": false,
        "imageDir": [
            "exmaple/01-image-folder"
        ],
        "pickFirstImageToBeBookCover": false,
        "debug": false,
        "bookTableOfContent": [
            {
                "type": "imageDir",
                "name": "01-image-folder",
                "imageDir": "exmaple/01-image-folder"
            }
        ],
        "imageFormatConversionTable": {}
    },
    "output": {
        "path": "/tmp/test.epub",
        "size": 361025,
        "sizeReadable": "352.56 KB",
        "imageCount": 0,
        "timeCost": [
            5.221366882324219e-05,
            5.1021575927734375e-05,
            0.012903928756713867
        ]
    },
    "error": [],
    "version": "1.0.0"
}

% unzip -l /tmp/test.epub 
Archive:  /tmp/test.epub
  Length      Date    Time    Name
---------  ---------- -----   ----
       20  12-17-2023 10:32   mimetype
      251  12-17-2023 10:32   META-INF/container.xml
     1802  12-17-2023 10:32   EPUB/content.opf
       55  12-17-2023 10:32   EPUB/default.css
   128903  12-17-2023 10:32   EPUB/img-1-000002.jpg
      619  12-17-2023 10:32   EPUB/xhtml-1-000003.xhtml
    88590  12-17-2023 10:32   EPUB/img-1-000004.jpg
      619  12-17-2023 10:32   EPUB/xhtml-1-000005.xhtml
   142203  12-17-2023 10:32   EPUB/img-1-000006.jpg
      620  12-17-2023 10:32   EPUB/xhtml-1-000007.xhtml
      411  12-17-2023 10:32   EPUB/toc.ncx
      333  12-17-2023 10:32   EPUB/nav.xhtml
---------                     -------
   364426                     12 files

2. From multiple image folders to an EPUB book

% tree 02-multiple-image-folders 
02-multiple-image-folders
├── first
│   ├── 01.jpg
│   ├── 02.jpg
│   └── 03.jpg
└── second
    ├── 01.jpg
    ├── 02.jpg
    ├── 03.jpg
    ├── 04.jpg
    └── 05.jpg

3 directories, 8 files

% epub-image-helper 02-multiple-image-folders
{
    "status": true,
    "input": {
        "output": "/tmp/test.epub",
        "bookConfig": "{}",
        "bookCover": "",
        "bookId": "011af0b8-0340-4f5d-b22a-10dbc0a52eea",
        "bookTitle": "Unknown",
        "bookAuthor": "Unknown",
        "epubcheck": false,
        "imageDir": [
            "exmaple/02-multiple-image-folders"
        ],
        "pickFirstImageToBeBookCover": false,
        "debug": false,
        "bookTableOfContent": [
            {
                "type": "imageDir",
                "name": "02-multiple-image-folders",
                "imageDir": "exmaple/02-multiple-image-folders"
            }
        ],
        "imageFormatConversionTable": {}
    },
    "output": {
        "path": "/tmp/test.epub",
        "size": 26444959,
        "sizeReadable": "25.22 MB",
        "imageCount": 0,
        "timeCost": [
            4.696846008300781e-05,
            0.00010395050048828125,
            0.5822200775146484
        ]
    },
    "error": [],
    "version": "1.0.0"
}

% unzip -l /tmp/test.epub 
Archive:  /tmp/test.epub
  Length      Date    Time    Name
---------  ---------- -----   ----
       20  12-17-2023 10:57   mimetype
      251  12-17-2023 10:57   META-INF/container.xml
     2807  12-17-2023 10:57   EPUB/content.opf
       55  12-17-2023 10:57   EPUB/default.css
   128903  12-17-2023 10:57   EPUB/img-1-000002.jpg
      629  12-17-2023 10:57   EPUB/xhtml-1-000003.xhtml
    88590  12-17-2023 10:57   EPUB/img-1-000004.jpg
      629  12-17-2023 10:57   EPUB/xhtml-1-000005.xhtml
   142203  12-17-2023 10:57   EPUB/img-1-000006.jpg
      629  12-17-2023 10:57   EPUB/xhtml-1-000007.xhtml
 11474510  12-17-2023 10:57   EPUB/img-1-000008.jpg
      631  12-17-2023 10:57   EPUB/xhtml-1-000009.xhtml
  6709355  12-17-2023 10:57   EPUB/img-1-000010.jpg
      631  12-17-2023 10:57   EPUB/xhtml-1-000011.xhtml
  2372710  12-17-2023 10:57   EPUB/img-1-000012.jpg
      631  12-17-2023 10:57   EPUB/xhtml-1-000013.xhtml
  5484157  12-17-2023 10:57   EPUB/img-1-000014.jpg
      631  12-17-2023 10:57   EPUB/xhtml-1-000015.xhtml
   114318  12-17-2023 10:57   EPUB/img-1-000016.jpg
      630  12-17-2023 10:57   EPUB/xhtml-1-000017.xhtml
      411  12-17-2023 10:57   EPUB/toc.ncx
      333  12-17-2023 10:57   EPUB/nav.xhtml
---------                     -------
 26523664                     22 files

% epub-image-helper 02-multiple-image-folders/first 02-multiple-image-folders/second 
{
    "status": true,
    "input": {
        "output": "/tmp/test.epub",
        "bookConfig": "{}",
        "bookCover": "",
        "bookId": "5026a99b-257b-4c1d-bb51-d4c2fc6e3610",
        "bookTitle": "Unknown",
        "bookAuthor": "Unknown",
        "epubcheck": false,
        "imageDir": [
            "exmaple/02-multiple-image-folders/first",
            "exmaple/02-multiple-image-folders/second"
        ],
        "pickFirstImageToBeBookCover": false,
        "debug": false,
        "bookTableOfContent": [
            {
                "type": "imageDir",
                "name": "first",
                "imageDir": "exmaple/02-multiple-image-folders/first"
            },
            {
                "type": "imageDir",
                "name": "second",
                "imageDir": "exmaple/02-multiple-image-folders/second"
            }
        ],
        "imageFormatConversionTable": {}
    },
    "output": {
        "path": "/tmp/test.epub",
        "size": 26444875,
        "sizeReadable": "25.22 MB",
        "imageCount": 0,
        "timeCost": [
            5.984306335449219e-05,
            7.414817810058594e-05,
            0.5851681232452393
        ]
    },
    "error": [],
    "version": "1.0.0"
}

% unzip -l /tmp/test.epub 
Archive:  /tmp/test.epub
  Length      Date    Time    Name
---------  ---------- -----   ----
       20  12-17-2023 11:01   mimetype
      251  12-17-2023 11:01   META-INF/container.xml
     2807  12-17-2023 11:01   EPUB/content.opf
       55  12-17-2023 11:01   EPUB/default.css
   128903  12-17-2023 11:01   EPUB/img-1-000002.jpg
      609  12-17-2023 11:01   EPUB/xhtml-1-000003.xhtml
    88590  12-17-2023 11:01   EPUB/img-1-000004.jpg
      609  12-17-2023 11:01   EPUB/xhtml-1-000005.xhtml
   142203  12-17-2023 11:01   EPUB/img-1-000006.jpg
      610  12-17-2023 11:01   EPUB/xhtml-1-000007.xhtml
 11474510  12-17-2023 11:01   EPUB/img-2-000008.jpg
      612  12-17-2023 11:01   EPUB/xhtml-2-000009.xhtml
  6709355  12-17-2023 11:01   EPUB/img-2-000010.jpg
      612  12-17-2023 11:01   EPUB/xhtml-2-000011.xhtml
  2372710  12-17-2023 11:01   EPUB/img-2-000012.jpg
      612  12-17-2023 11:01   EPUB/xhtml-2-000013.xhtml
  5484157  12-17-2023 11:01   EPUB/img-2-000014.jpg
      612  12-17-2023 11:01   EPUB/xhtml-2-000015.xhtml
   114318  12-17-2023 11:01   EPUB/img-2-000016.jpg
      611  12-17-2023 11:01   EPUB/xhtml-2-000017.xhtml
      411  12-17-2023 11:01   EPUB/toc.ncx
      333  12-17-2023 11:01   EPUB/nav.xhtml
---------                     -------
 26523510                     22 files

2. Convert all images from a PDF file to an EPUB file.

% pdfinfo /tmp/test.pdf | grep Pages
Pages:           3

% echo '{"bookTableOfContent": [ { "type": "imagePdf", "name": "Test", "imagePdf": "/tmp/test.pdf", "workDir": "/tmp/workDir-test.pdf", "imagePdfSaveFormat": "jpg" , "imagePdfSaveQuality": 100 } ]}' | epub-image-helper --bookConfig @-
{
    "status": false,
    "input": {
        "output": "/tmp/test.epub",
        "bookConfig": "@-",
        "bookCover": "",
        "bookId": "438e9899-eafc-42ef-bc21-c0134c4f82f4",
        "bookTitle": "Unknown",
        "bookAuthor": "Unknown",
        "epubcheck": false,
        "imageDir": [],
        "pickFirstImageToBeBookCover": false,
        "debug": false,
        "bookTableOfContent": [
            {
                "type": "imagePdf",
                "name": "Test",
                "imagePdf": "/tmp/test.pdf",
                "workDir": "/tmp/workDir-test.pdf",
                "imagePdfSaveFormat": "jpg",
                "imagePdfSaveQuality": 100
            }
        ],
        "imageFormatConversionTable": {},
        "stdin": "{\"bookTableOfContent\": [ { \"type\": \"imagePdf\", \"name\": \"Test\", \"imagePdf\": \"/tmp/test.pdf\", \"workDir\": \"/tmp/workDir-test.pdf\", \"imagePdfSaveFormat\": \"jpg\" , \"imagePdfSaveQuality\": 100 } ]}\n"
    },
    "output": {
        "path": null,
        "size": 0,
        "sizeReadable": null,
        "imageCount": 0,
        "timeCost": [
            2.9087066650390625e-05,
            3.0279159545898438e-05
        ]
    },
    "error": [
        {
            "status": false,
            "error": [
                "type=\"imagePdf\" error, \"workDir\" not exists: index=0, item={'type': 'imagePdf', 'name': 'Test', 'imagePdf': '/tmp/test.pdf', 'workDir': '/tmp/workDir-test.pdf', 'imagePdfSaveFormat': 'jpg', 'imagePdfSaveQuality': 100}"
            ],
            "input": [
                {
                    "type": "imagePdf",
                    "name": "Test",
                    "imagePdf": "/tmp/test.pdf",
                    "workDir": "/tmp/workDir-test.pdf",
                    "imagePdfSaveFormat": "jpg",
                    "imagePdfSaveQuality": 100
                }
            ],
            "output": [],
            "totalImage": 0,
            "timeCost": []
        }
    ],
    "version": "1.0.0"
}

% mkdir /tmp/workDir-test.pdf

% echo '{"bookTableOfContent": [ { "type": "imagePdf", "name": "Test", "imagePdf": "/tmp/test.pdf", "workDir": "/tmp/workDir-test.pdf", "imagePdfSaveFormat": "jpg" , "imagePdfSaveQuality": 100 } ]}' | epub-image-helper --bookConfig @-
{
    "status": true,
    "input": {
        "output": "/tmp/test.epub",
        "bookConfig": "@-",
        "bookCover": "",
        "bookId": "1e788bee-4f66-49f5-bce3-c412a7a4a348",
        "bookTitle": "Unknown",
        "bookAuthor": "Unknown",
        "epubcheck": false,
        "imageDir": [],
        "pickFirstImageToBeBookCover": false,
        "debug": false,
        "bookTableOfContent": [
            {
                "type": "imagePdf",
                "name": "Test",
                "imagePdf": "/tmp/test.pdf",
                "workDir": "/tmp/workDir-test.pdf",
                "imagePdfSaveFormat": "jpg",
                "imagePdfSaveQuality": 100
            }
        ],
        "imageFormatConversionTable": {},
        "stdin": "{\"bookTableOfContent\": [ { \"type\": \"imagePdf\", \"name\": \"Test\", \"imagePdf\": \"/tmp/test.pdf\", \"workDir\": \"/tmp/workDir-test.pdf\", \"imagePdfSaveFormat\": \"jpg\" , \"imagePdfSaveQuality\": 100 } ]}\n"
    },
    "output": {
        "path": "/tmp/test.epub",
        "size": 361006,
        "sizeReadable": "352.54 KB",
        "imageCount": 0,
        "timeCost": [
            3.0994415283203125e-05,
            0.035225868225097656,
            0.013682126998901367
        ]
    },
    "error": [],
    "version": "1.0.0"
}

% unzip -l /tmp/test.epub 
Archive:  /tmp/test.epub
  Length      Date    Time    Name
---------  ---------- -----   ----
       20  12-17-2023 13:37   mimetype
      251  12-17-2023 13:37   META-INF/container.xml
     1802  12-17-2023 13:37   EPUB/content.opf
       55  12-17-2023 13:37   EPUB/default.css
   128903  12-17-2023 13:37   EPUB/img-1-000002.jpg
      608  12-17-2023 13:37   EPUB/xhtml-1-000003.xhtml
    88590  12-17-2023 13:37   EPUB/img-1-000004.jpg
      608  12-17-2023 13:37   EPUB/xhtml-1-000005.xhtml
   142203  12-17-2023 13:37   EPUB/img-1-000006.jpg
      609  12-17-2023 13:37   EPUB/xhtml-1-000007.xhtml
      411  12-17-2023 13:37   EPUB/toc.ncx
      333  12-17-2023 13:37   EPUB/nav.xhtml
---------                     -------
   364393                     12 files

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

epub_image_helper-1.0.7.tar.gz (18.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

epub_image_helper-1.0.7-py3-none-any.whl (16.3 kB view details)

Uploaded Python 3

File details

Details for the file epub_image_helper-1.0.7.tar.gz.

File metadata

  • Download URL: epub_image_helper-1.0.7.tar.gz
  • Upload date:
  • Size: 18.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for epub_image_helper-1.0.7.tar.gz
Algorithm Hash digest
SHA256 b7b9a66e6b8a54b3139d9c46c4d7096428242d9bb9d46396fb2d9e9b08816058
MD5 3e3e68cbca210d0b0d0e059f29715808
BLAKE2b-256 80f8e403c0a658b0c810dcab158709616cdd34d7082f750d82e9f6798aa3df4b

See more details on using hashes here.

Provenance

The following attestation bundles were made for epub_image_helper-1.0.7.tar.gz:

Publisher: python-publish.yml on changyy/epub-image-helper

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file epub_image_helper-1.0.7-py3-none-any.whl.

File metadata

File hashes

Hashes for epub_image_helper-1.0.7-py3-none-any.whl
Algorithm Hash digest
SHA256 a6d735b95d82c7c452be5376c4bd189e17f4607ed0fdd29cdab839d0010ad40b
MD5 b4a3b5533682187f5ba7f05fc21108ff
BLAKE2b-256 99be1b7bc2c77a7889fc316937be2a8c47d2623c8271750e9e41ef8201f4c6b9

See more details on using hashes here.

Provenance

The following attestation bundles were made for epub_image_helper-1.0.7-py3-none-any.whl:

Publisher: python-publish.yml on changyy/epub-image-helper

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page