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.

These details have not been verified by PyPI

Project links

Project description

epub-image-helper

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

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

1.0.6

Jan 7, 2024

1.0.5

Dec 26, 2023

This version

1.0.4

Dec 25, 2023

1.0.3

Dec 21, 2023

1.0.2

Dec 20, 2023

1.0.1

Dec 17, 2023

1.0.0

Dec 17, 2023

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.4.tar.gz (18.5 kB view details)

Uploaded Dec 25, 2023 Source

Built Distribution

epub_image_helper-1.0.4-py3-none-any.whl (16.2 kB view details)

Uploaded Dec 25, 2023 Python 3

File details

Details for the file epub-image-helper-1.0.4.tar.gz.

File metadata

Download URL: epub-image-helper-1.0.4.tar.gz
Upload date: Dec 25, 2023
Size: 18.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/4.0.2 CPython/3.11.7

File hashes

Hashes for epub-image-helper-1.0.4.tar.gz
Algorithm	Hash digest
SHA256	`06d042fd2ffc8f07da6dce39b80a4e775adf42788add4b115e370ce54822e440`
MD5	`831aa94db83f7d2e61a44f3fc342879d`
BLAKE2b-256	`7a38d2890ec1f96fdb7e763a44947566c9064bfae75938b9706e2a0271572d0b`

See more details on using hashes here.

File details

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

File metadata

Download URL: epub_image_helper-1.0.4-py3-none-any.whl
Upload date: Dec 25, 2023
Size: 16.2 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/4.0.2 CPython/3.11.7

File hashes

Hashes for epub_image_helper-1.0.4-py3-none-any.whl
Algorithm	Hash digest
SHA256	`a358811d14b0f2157c9ef7c1a5eca6c7d00ca1f604c25beb20a5e1114a4a8c13`
MD5	`f256089bf1f909c7a1dbdd73db96491a`
BLAKE2b-256	`247991a8807feed957ab0e7dd549decf449495396d26538bde681ab766aac6e3`