Updating readme, removing obsolete files

This commit is contained in:
Christian Aribaud 2023-05-21 22:50:03 +02:00
parent 22399551dc
commit 8f777a2a1a
7 changed files with 83 additions and 69 deletions

View File

@ -2,32 +2,43 @@
![](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png)
Melpomene is a a simple, easy to integrate webcomic reading utility .
Melpomene is a a simple, HTML/CSS/JS webcomic reading utility .
It allows people to look through your webcomic like they would in real life : panel by panel. It displays your pages through a series of zooms you defines beforehand.
Melpomene uses SVGs as input to defines the zooms. It allows you to use any SVG editor as a "What You See Is What You Get" editor.
To avoid writing the zooms informations by hand, Melpomene utility scripts uses SVGs as input to defines the zooms. It allows you to use any SVG editor as a "What You See Is What You Get" editor.
This repository host a small demo you can open in your browser : the [episode 35 of pepper and carrot](https://www.peppercarrot.com/en/webcomic/ep35_The-Reflection.html) (see Credits). You can open `demos/pepper_and_carrot_e35_lowres.html` and `demos/pepper_and_carrot_e35_highres.html` to see Mepomene in action!
This repository host a small demo you can open in your browser : the [episode 35 of pepper and carrot](https://www.peppercarrot.com/en/webcomic/ep35_The-Reflection.html) (see Credits). You can open the HTML files in the `demos` folder to see Mepomene in action!
Melpomene main repository is [https://git.aribaud.net/caribaud/melpomene](https://git.aribaud.net/caribaud/melpomene)
# How Melpomene works
It works with :
+ HTML, CSS and Javascript snipets you can put in your web page to add the webcomic reader
+ A Javascript file describing the various informations required by the reader
+ A Python script, used to generate the above Javascript configuration file
```mermaid
flowchart TB
page([Your comic pages]) -- use in --> svgedit[SVG editor<br>e.g. Inkscape, etc...]
svgedit -- export --> svg([SVGs with<br>zooms defined])
svg -- use in --> confgen[Melpomene<br>config generator]
confgen --> conf([json<br>config])
conf & html([HTML snipet]) & js([JS snipet]) & css([CSS snipet]) -- use / import into --> webpage([Your web page])
svg -- use in --> gen[Melpomene<br>config generator]
gen -- generate --> html([Melpomene HTML snipet])
html -- copy into --> webpage([Your web page])
js([melpomene.js]) & css([melpomene.css]) -- include into --> webpage
```
Melpomene is mainly one JS file and one CSS file. You only need to include them in you web page. They are :
+ `melpomene.js`
+ `melpomene.css`
The JS files expect you to write some very specific HTML tags to be able to work.
To simplify things, you only need to copy-paste the content of `melpomene.html` into your own page and change a few things :
+ `data-pages-width` must be set to your comic pages width in px
+ `data-pages-height` must be set to your comic pages height in px
+ You must duplicate the `img` tag for each of you comic page and :
+ set `url` to the actual URL of your page
+ set `data-zooms` with the zooms information, like so : `<zoom 1 width>, <zoom 1 height>, <zoom 1 x offset>, <zoom 1 y offset>; <zoom 2 width> ...`
+ example : `<img loading="lazy" src="https://www.peppercarrot.com/0_sources/ep35_The-Reflection/hi-res/en_Pepper-and-Carrot_by-David-Revoy_E35P01.jpg" data-zooms="2481.0,1327.1057,0.0,0.0;593.15338,1076.4635,0.0,1364.053;890.72864,491.29874,830.81415,1751.5;2481.0,1078.4192,0.0,1364.053;562.77032,909.44702,102.48115,2491.6567;920.74463,909.44702,698.55927,2491.6567;728.776,909.44702,1652.3695,2491.6567"/>`
Because doing this by hand would be very tedious, Melpomene comes with an helper script that allows generating that HTML for you from SVGs.
## Limitations
The following limitations are known and will be improved upon :
@ -53,42 +64,25 @@ To create the zooms for a comic page, what you need to do is :
3. Once you are done, save the SGV
## Generating the configuration files
## Generating the HTML files
Once the SVG for your pages are done, put them in one folder. Then, you can run the zoom generator.
You need to open a terminal and then run :
+ `python zooms_generator.py <path to the SVG folder> zooms_data.json` on windows
+ `python3 zooms_generator.py <path to the SVG folder> zooms_data.json` on linux
+ `python zooms_generator.py <path to the SVG folder> html -p <prefix of the img's url> -e <extension of the img's url>`
+ For example, if your comic pages are hosted at `static/comic/page_x.jpg`, the svg must be named `page_x.svg`
and you must run `python zooms_generator.py <path to the SVG folder> html -p /static/comic/ -e jpg`
+ It will generate the following `img` tag : `<img loading="lazy" src="static/comic/page_x.jpg" data-zooms="..."/>`
The pages need to be in alphabetical order! It assumes the first page is page 1, the next one is page 2, etc..
The script will then generate the file `zooms_data.json`.
The script will then generate the file `melpomene_data.html`.
If you wish to run a custom generation process, this generator can output a JSON or a JS file as well, run `python zooms_generator.py -h` for help
You are now ready to integrate Melpomene in your website!
## Integrating Melpomene
Let's assume your site is `https://my.website/`.
You now need :
1. Host the Melpomene Javascript and CSS files in your website, e.g. at `https://my.website/melptomene.js` and `https://my.website/melptomene.css`
2. Host the zooms data on your website, e.g. at `https://my.website/zooms_data.js`
2. Include the various parts of the HTML snipets :
1. `melpomene_head.html` goes in the `head` tag of your page
* You may need to change the `href` values to where you uploaded the CSS file.
2. `melpomene_reader.html` goes where you want somewhere within the `body` tag of your page
* Change `data-pages-width` and `data-pages-height` with the actual width and height of your pages
* Change `https://link.to.my/comic/page.jpg` to the actual URL of your comic pages and duplicate the `img`
tag for each of them
3. `melpomene_js.html` goes right after the `body` tag of your page.
* You may need to change the `href` values to where you uploaded the JS files.
You can now open your page and should see the results.
If you are having troubles, you can open the demo files to see how it was done.
# Credits
Most examples and the documentation of Melpomene uses illustrations from David "Deevad" Revoy's "Pepper & Carrot" webcomic, which is published under CC-BY 4.0. Full licence [here](https://www.peppercarrot.com/en/license/index.html).

View File

@ -11,13 +11,10 @@
<body>
<!-- melpomene_reader.html import -->
<!-- Melpomene comic reader -->
<!-- CC-BY-NC-SA https://git.aribaud.net/caribaud/melpomene/ -->
<div id="reader-frame">
<div id="reader-content-frame">
<div id="reader-pages" class="animated" data-pages-width="2481" data-pages-height="3503" hidden>
<img loading="lazy" src="https://www.peppercarrot.com/0_sources/ep35_The-Reflection/hi-res/en_Pepper-and-Carrot_by-David-Revoy_E35P01.jpg"/>
<img loading="lazy" src="https://www.peppercarrot.com/0_sources/ep35_The-Reflection/hi-res/en_Pepper-and-Carrot_by-David-Revoy_E35P02.jpg"/>
@ -32,7 +29,6 @@
<img loading="lazy" src="https://www.peppercarrot.com/0_sources/ep35_The-Reflection/hi-res/en_Pepper-and-Carrot_by-David-Revoy_E35P11.jpg"/>
<img loading="lazy" src="https://www.peppercarrot.com/0_sources/ep35_The-Reflection/hi-res/en_Pepper-and-Carrot_by-David-Revoy_E35P12.jpg"/>
</div>
<div id="focus-overlay" class="flex-col fill">
<div class="grow obscured animated"></div>
<div id="focus-overlay-height" class="flex animated" style="height:100%">
@ -42,12 +38,10 @@
</div>
<div class="grow obscured animated"></div>
</div>
<div id="nav-controls" class="fill">
<div class="left" id="nav-left" onclick="moveReader(false,false)"></div>
<div class="right" id="nav-right" onclick="moveReader(true,false)"></div>
</div>
<div id="help-menu">
<div id="help-controls" style="opacity:1; transform: translate(0,0);">
<div><div class="key">&larr;</div>/ scroll up / clic : previous</div>
@ -58,9 +52,7 @@
<div><div class="key">V</div>: Toggle panel / page viewing mode</div>
</div>
</div>
</div>
<div id="reader-progress-container">
<div id="reader-progress-bar"></div>
<div id="reader-progress-pages"></div>

View File

@ -11,13 +11,10 @@
<body>
<!-- melpomene_reader.html import -->
<!-- Melpomene comic reader -->
<!-- CC-BY-NC-SA https://git.aribaud.net/caribaud/melpomene/ -->
<div id="reader-frame">
<div id="reader-content-frame">
<div id="reader-pages" class="animated" data-pages-width="2481" data-pages-height="3503" hidden>
<img loading="lazy" src="https://www.peppercarrot.com/0_sources/ep35_The-Reflection/hi-res/en_Pepper-and-Carrot_by-David-Revoy_E35P01.jpg" data-zooms="2481.0,1327.1057,0.0,0.0;593.15338,1076.4635,0.0,1364.053;890.72864,491.29874,830.81415,1751.5;2481.0,1078.4192,0.0,1364.053;562.77032,909.44702,102.48115,2491.6567;920.74463,909.44702,698.55927,2491.6567;728.776,909.44702,1652.3695,2491.6567"/>
<img loading="lazy" src="https://www.peppercarrot.com/0_sources/ep35_The-Reflection/hi-res/en_Pepper-and-Carrot_by-David-Revoy_E35P02.jpg" data-zooms="1459.9161,960.62878,99.857468,103.85177;788.87384,960.62878,1593.7252,103.85177;455.35007,305.56384,389.44412,1376.0359;2282.7415,760.914,99.857475,1114.4093;1069.9728,496.29166,101.85461,1928.2478;1209.7733,496.29166,1172.3267,1928.2478;788.87402,926.67731,101.85462,2474.468;415.40707,926.67731,924.68018,2474.468;1008.5604,926.67731,1372.0416,2474.468"/>
@ -32,8 +29,6 @@
<img loading="lazy" src="https://www.peppercarrot.com/0_sources/ep35_The-Reflection/hi-res/en_Pepper-and-Carrot_by-David-Revoy_E35P11.jpg" data-zooms="830.81415,1194.2953,97.860321,101.85461;774.89398,1198.2897,960.62885,99.857468;609.13055,1192.2982,1769.4744,101.85461;363.4812,868.75995,99.857468,1348.0758;1495.8649,870.75714,493.2959,1346.0787;357.48975,870.75714,2023.1123,1348.0758;529.24457,499.28735,103.85177,2280.7446;531.24176,687.01941,99.857468,2716.123;1022.5405,1120.4008,669.04504,2280.7446;657.06213,1120.4008,1725.5371,2280.7446"/>
<img loading="lazy" src="https://www.peppercarrot.com/0_sources/ep35_The-Reflection/hi-res/en_Pepper-and-Carrot_by-David-Revoy_E35P12.jpg" data-zooms="704.99371,341.51254,619.11633,281.59805;393.43842,551.21326,1459.9161,159.77196;2280.7446,691.01367,99.857468,101.85461;718.97375,1198.2897,99.857468,840.79987;712.9823,1196.2925,850.78564,842.79706;780.88538,1192.2982,1599.7167,842.79706;2366.6221,1445.9362,61.911629,2049.0752;922.68298,551.21326,984.59467,2378.605;631.09918,211.69783,1851.3574,3289.3049"/>
</div>
<div id="focus-overlay" class="flex-col fill">
<div class="grow obscured animated"></div>
<div id="focus-overlay-height" class="flex animated" style="height:100%">
@ -43,12 +38,10 @@
</div>
<div class="grow obscured animated"></div>
</div>
<div id="nav-controls" class="fill">
<div class="left" id="nav-left" onclick="moveReader(false,false)"></div>
<div class="right" id="nav-right" onclick="moveReader(true,false)"></div>
</div>
<div id="help-menu">
<div id="help-controls" style="opacity:1; transform: translate(0,0);">
<div><div class="key">&larr;</div>/ scroll up / clic : previous</div>
@ -59,9 +52,7 @@
<div><div class="key">V</div>: Toggle panel / page viewing mode</div>
</div>
</div>
</div>
<div id="reader-progress-container">
<div id="reader-progress-bar"></div>
<div id="reader-progress-pages"></div>
@ -69,6 +60,7 @@
</div>
<!-- End of Melpomene comic reader -->
</body>
<!-- melpomene_js.html import -->

View File

@ -2,13 +2,11 @@
<!-- CC-BY-NC-SA https://git.aribaud.net/caribaud/melpomene/ -->
<div id="reader-frame">
<div id="reader-content-frame">
<div id="reader-pages" class="animated" data-pages-width="9999" data-pages-height="9999" hidden>
<img loading="lazy" src="https://link.to.my/comic/page.jpg"/>
<!-- Change "https://link.to.my/comic/page.jpg" with you page URL. -->
<!-- You can add more pages by duplicating the line -->
<!-- replace all 'xxxx' with the actual value -->
<div id="reader-pages" class="animated" data-pages-width="xxxx" data-pages-height="xxxx" hidden>
<img loading="lazy" src="xxxx" data-zooms="xxxx"/>
<!-- duplicate img for each comic page -->
</div>
<div id="focus-overlay" class="flex-col fill">
<div class="grow obscured animated"></div>
<div id="focus-overlay-height" class="flex animated" style="height:100%">
@ -18,12 +16,10 @@
</div>
<div class="grow obscured animated"></div>
</div>
<div id="nav-controls" class="fill">
<div class="left" id="nav-left" onclick="moveReader(false,false)"></div>
<div class="right" id="nav-right" onclick="moveReader(true,false)"></div>
</div>
<div id="help-menu">
<div id="help-controls" style="opacity:1; transform: translate(0,0);">
<div><div class="key">&larr;</div>/ scroll up / clic : previous</div>
@ -34,9 +30,7 @@
<div><div class="key">V</div>: Toggle panel / page viewing mode</div>
</div>
</div>
</div>
<div id="reader-progress-container">
<div id="reader-progress-bar"></div>
<div id="reader-progress-pages"></div>

View File

@ -1 +0,0 @@
<link rel="stylesheet" href="melpomene.css">

View File

@ -1,2 +0,0 @@
<script src="zooms_data.js"></script>
<script src="melpomene.js"></script>

View File

@ -10,6 +10,47 @@ import argparse
from pathlib import Path
HTML_START_CONSTANT = """\
<!-- Melpomene comic reader -->
<!-- CC-BY-NC-SA https://git.aribaud.net/caribaud/melpomene/ -->
<div id="reader-frame">
<div id="reader-content-frame">
"""
HTML_END_CONSTANT = """\
<div id="focus-overlay" class="flex-col fill">
<div class="grow obscured animated"></div>
<div id="focus-overlay-height" class="flex animated" style="height:100%">
<div class="grow obscured animated"></div>
<div id="focus-overlay-width" class="focus animated" style="width:100%"></div>
<div class="grow obscured animated"></div>
</div>
<div class="grow obscured animated"></div>
</div>
<div id="nav-controls" class="fill">
<div class="left" id="nav-left" onclick="moveReader(false,false)"></div>
<div class="right" id="nav-right" onclick="moveReader(true,false)"></div>
</div>
<div id="help-menu">
<div id="help-controls" style="opacity:1; transform: translate(0,0);">
<div><div class="key">&larr;</div>/ scroll up / clic : previous</div>
<div><div class="key">&rarr;</div>/ scroll down / clic : next</div>
<div>-----------------------</div>
<div><div class="key">F</div>: Toggle fullscreen</div>
<div><div class="key">P</div>: Toggle progress bar</div>
<div><div class="key">V</div>: Toggle panel / page viewing mode</div>
</div>
</div>
</div>
<div id="reader-progress-container">
<div id="reader-progress-bar"></div>
<div id="reader-progress-pages"></div>
</div>
</div>
<!-- End of Melpomene comic reader -->
"""
def extract_zooms(src_folder):
folder = Path(src_folder)
@ -77,15 +118,19 @@ def write_html(zooms, dest_file, pages_width, pages_height, prefix, extention):
with open(dest_file, "w") as data_file:
data_file.write(f'<div id="reader-pages" class="animated" data-pages-width="{pages_width}" data-pages-height="{pages_height}" hidden>\n')
data_file.write(HTML_START_CONSTANT)
data_file.write(f' <div id="reader-pages" class="animated" data-pages-width="{pages_width}" data-pages-height="{pages_height}" hidden>\n')
for page_idx in sorted(zooms.keys()):
img_url = f"{prefix}{zooms[page_idx]['name']}.{extention}"
zoom_html_data = [','.join([str(zoom) for zoom in page_zooms]) for page_zooms in zooms[page_idx]["zooms"]]
zoom_html_str = ';'.join(zoom_html_data)
data_file.write(f' <img loading="lazy" src="{img_url}" data-zooms="{zoom_html_str}"/>\n')
data_file.write(f' <img loading="lazy" src="{img_url}" data-zooms="{zoom_html_str}"/>\n')
data_file.write(f'</div>\n')
data_file.write(f' </div>\n')
data_file.write(HTML_END_CONSTANT)
def generate_argparse():
""" Generate Melpomene's generator input parser"""