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
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:
- https://github.com/aerkalov/ebooklib/pulls
- https://pypi.org/project/EbookLib.changyy/
- https://github.com/changyy/ebooklib/tree/release
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
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.6.tar.gz
(18.6 kB
view hashes)
Built Distribution
Close
Hashes for epub_image_helper-1.0.6-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 772a3864e826091b2ffad1e3759cfec6417c2c8a08983e958bd9e0cd5243218e |
|
| MD5 | cf51d5703c48d75fac5e3e20b1988c7c |
|
| BLAKE2b-256 | 06a6dd860b0a1a3ddd0a33be02566d8c632778b3cafc85371db014dff91cb22c |
