1
0
mirror of https://github.com/bpatrik/pigallery2.git synced 2025-01-02 03:37:54 +02:00

Update documentation #725

This commit is contained in:
Patrik J. Braun 2023-09-21 23:17:50 +02:00
parent f5ed66d0ad
commit 11a300b0eb
29 changed files with 1112 additions and 390 deletions

1137
MANPAGE.md

File diff suppressed because one or more lines are too long

View File

@ -153,73 +153,7 @@ apt-get install build-essential libkrb5-dev gcc g++
## 3. Feature list
* supported formats [full list here](https://github.com/bpatrik/pigallery2/blob/master/src/common/SupportedFormats.ts):
* images: **jpg, jpeg, jpe, webp, png, gif, svg**
* videos: **mp4, ogg, ogv, webm**
* with (built-in) transcoding: avi, mkv, mov, wmv, flv, mts, m2ts, mpg, 3gp, m4v, mpeg, vob, divx, xvid, ts
* **Rendering directories as it is**
* Listing subdirectories recursively
* Listing photos in a nice grid layout
* showing **tag/keywords, locations, GPS coordinates** for photos
* rendering photos on demand (on scroll)
* **On the fly thumbnail generation** in several sizes
* prioritizes thumbnail generation (generating thumbnail first for the visible photos)
* saving generated thumbnails to TEMP folder for reuse
* supporting multi-core CPUs
* supporting hardware acceleration ([sharp](https://github.com/lovell/sharp))
* Custom lightbox for full screen photo and video viewing
* keyboard support for navigation
* showing low-res thumbnail while full image loads
* Information panel for showing **Exif and IPTC info**
* Automatic playing
* gesture support (swipe left, right, up)
* shortcut support
* On the fly photo downscaling for faster load [#50](https://github.com/bpatrik/pigallery2/issues/50)
* on zoom, the original photo loads
* Client side caching (directories and search results)
* Rendering **photos** with GPS coordinates **on open street maps**
* .gpx file support: rendering paths to map
* supports [OSM](https://www.openstreetmap.org) and [Mapbox](https://www.mapbox.com) by default, but you can add any provider that has a tile url
* **Two modes: SQL database and no-database mode**
* both modes support
* user management
* password protection can be disabled/enabled
* database mode supports:
* faster directory listing
* searching
* instant search, auto complete
* sharing
* setting link expiration time
* Faces (persons) support
* reads Adobe's XMP Face region metadata. (It is defined by the Metadata Working Group (MWG).)
* shows face bounding box over images
* internalization / translation support
* currently supported languages: eng, hun, ro, ru, fr, many other
* Nice design
* responsive design (phone, tablet desktop support)
* Setup page
* Random photo url
* You can generate an url that returns a random photo from your gallery. You can use this feature to develop 3rd party applications, like: changing desktop background
* duplicate photo detection
* video support
* fully supports `*.mp4` files and partially (might have errors with safari and IE) supports `*.ogg`, `*.ogv`, `*.webm` files
* uses ffmpeg and ffprobe to generate video thumbnails
* can transcode videos to mp4 for better support
* job scheduling support, with the following supported task: [#92](https://github.com/bpatrik/pigallery2/issues/92)
* converting/transcoding videos [#66](https://github.com/bpatrik/pigallery2/issues/66) [#71](https://github.com/bpatrik/pigallery2/issues/71)
* generating thumbnails
* generating converted photos
* cleaning up temp folder
* indexing db
* folder ignoring [#87](https://github.com/bpatrik/pigallery2/issues/87)
* `.pg2conf` UI modifying files. [#177](https://github.com/bpatrik/pigallery2/issues/177).
* List of these files are passed down to the UI modify its behaviour.
* Currently, supported custom, per folder sorting.
* Dockerized
* **Markdown based blogging support**
* you can write some note in the *.md files for every directory
* bug free :) - `In progress`
See: http://bpatrik.github.io/pigallery2/
## 4. Suggest/endorse new features
Unfortunately, lately I only have a limited time for this hobby project of mine.

BIN
docs/assets/albums.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 494 KiB

BIN
docs/assets/blog.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.4 MiB

BIN
docs/assets/faces.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 708 KiB

BIN
docs/assets/filters.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.5 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 2.7 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 2.7 KiB

After

Width:  |  Height:  |  Size: 3.8 KiB

BIN
docs/assets/lightbox.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.9 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 422 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 241 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 342 KiB

BIN
docs/assets/main_page.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.8 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 245 KiB

BIN
docs/assets/map.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.0 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 286 KiB

BIN
docs/assets/random_link.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.5 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 298 KiB

BIN
docs/assets/search.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 340 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 178 KiB

BIN
docs/assets/settings.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 303 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 280 KiB

BIN
docs/assets/sharing.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.5 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 66 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 190 KiB

BIN
docs/assets/video.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.9 MiB

View File

@ -31,7 +31,8 @@
</head>
<body class="text-center">
<a class="github-fork-ribbon" href="https://github.com/bpatrik/pigallery2" data-ribbon="Fork me on GitHub" title="Fork me on GitHub">Fork me on GitHub</a>
<a class="github-fork-ribbon" href="https://github.com/bpatrik/pigallery2" data-ribbon="Fork me on GitHub"
title="Fork me on GitHub">Fork me on GitHub</a>
<div class="cover-container d-flex w-100 h-100 p-3 mx-auto flex-column ">
<header class="masthead">
<div class="inner">
@ -52,7 +53,7 @@
<h3>
PiGallery 2 is a self-hosted directory-first photo gallery website.
</h3>
<a href="https://pigallery2.onrender.com/">Try our live demo! <span class="small">(First load may take up 30s, while the server boots up)</span></a>
<a href="https://pigallery2.onrender.com/">Try our live demo! <span class="small">(First load may take up 60s, while the server boots up)</span></a>
</div>
@ -66,10 +67,10 @@
data-icon="octicon-repo-forked"
data-show-count="true" aria-label="Fork bpatrik/pigallery2 on GitHub">Fork</a>
</div>
<img class="banner-photo" src="assets/main_page.jpg" style="width: 100%">
<img class="banner-photo" src="assets/main_page.png" style="width: 100%">
<div class="row">
<div class="col">
The gallery is a directory first gallery. It renders your directory structure as it is.
The gallery is a directory first gallery. It renders your read-only directory structure as it is.
Supports rich search queries and fully <a href="https://www.docker.com/">dockerized</a>.
</div>
</div>
@ -78,29 +79,34 @@
<div class="row feature">
<div class="col">
<div class="col-12 col-md-8 feature-image">
<img src="assets/lightbox.png" style="width: 100%">
</div>
<div class="col order-md-1">
<h3>Photo viewer</h3>
Nice photo viewer with optional information panel that shows all important information about the photo.
</div>
<div class="col-12 col-md-8">
<img class="card-img-right" src="assets/lightbox_info.jpg" style="width: 100%">
</div>
</div>
<div class="row feature">
<div class="col-12 col-md-8 order-last order-md-first">
<img class="card-img-right" src="assets/map.jpg" style="width: 100%">
<div class="col-12 col-md-8 feature-image">
<img src="assets/map.png" style="width: 100%">
</div>
<div class="col">
<h3>Map</h3>
PiGallery2 reads the location data of the photos and puts them on a nice map.
The gallery also supports *.gps file to show your tracked path on the map too.
It by default supports <a href="https://www.openstreetmap.org">OpenStreetMap</a> and <a
href="https://www.mapbox.com">Mapbox</a>, but you can also add you own favourite map provider.
The gallery also supports *.gpx file to show your tracked path on the map too.
It recognize different type of activities (like: running, flying) from the *.gpx files.
The app shows these activities with different color and icon on the map.
</div>
</div>
<div class="row feature">
<div class="col-12 col-md-8 feature-image">
<img src="assets/search.png">
</div>
<div class="col">
<h3>Advanced searching</h3>
App supports full <a href="https://en.wikipedia.org/wiki/Boolean_algebra">boolean logic</a> with negation and
@ -118,9 +124,6 @@
</div>
<div class="col-12 col-md-8">
<img class="card-img-right" src="assets/search.jpg">
</div>
</div>
<div class="row feature">
<div class="col">
@ -154,7 +157,8 @@
last-4-days:2-months-ago <br/>
last-4-days:2-years-ago <br/>
</code>
See all here: <a href="https://github.com/bpatrik/pigallery2/blob/5368b4ed4e1a61097dbc88aa076aaf9c21524a8d/src/frontend/app/ui/gallery/search/search-query-parser.service.ts#L9">search-query-parser.service.ts</a>.
See all here: <a
href="https://github.com/bpatrik/pigallery2/blob/5368b4ed4e1a61097dbc88aa076aaf9c21524a8d/src/frontend/app/ui/gallery/search/search-query-parser.service.ts#L9">search-query-parser.service.ts</a>.
<p/>
<h5>Bool expressions</h5>
<code class="code-block p-2 text-light rounded bg-secondary d-block">
@ -165,10 +169,12 @@
</code>
<p/>
<h5>Sort order</h5>
Add an empty file like <code class="code-block p-1 text-light rounded bg-secondary">.order_[ORDER].pg2conf</code>
Add an empty file like <code
class="code-block p-1 text-light rounded bg-secondary">.order_[ORDER].pg2conf</code>
to a folder to override the default sorting for that folder.
It's not recursively applied to subfolders.<br/>
Replace <code class="code-block p-1 text-light rounded bg-secondary">[ORDER]</code> in the above shown filename by one of the following values:<br/>
Replace <code class="code-block p-1 text-light rounded bg-secondary">[ORDER]</code> in the above shown filename
by one of the following values:<br/>
<code class="code-block p-2 text-light rounded bg-secondary d-block">
descending_name<br/>
ascending_name<br/>
@ -181,8 +187,8 @@
<div class="row feature">
<div class="col-12 col-md-8 order-last order-md-first">
<img class="card-img-right" src="assets/sharing.jpg" style="width: 100%">
<div class="col-12 col-md-8 feature-image">
<img src="assets/sharing.png" style="width: 100%">
</div>
<div class="col">
<h3>Sharing</h3>
@ -194,19 +200,8 @@
<div class="row feature">
<div class="col">
<h3>Easy settings</h3>
PiGallery2 has a rich settings page where you can easily set up the gallery.
<a href="https://pigallery2.onrender.com/admin">Click here to see all the setting in the live demo.</a>
</div>
<div class="col-12 col-md-8">
<img class="card-img-right" src="assets/settings.jpg" style="width: 100%">
</div>
</div>
<div class="row feature">
<div class="col-12 col-md-8 order-last order-md-first">
<img class="card-img-right" src="assets/video.jpg" style="width: 100%">
<div class="col-12 col-md-8 feature-image">
<img src="assets/video.png" style="width: 100%">
</div>
<div class="col">
<h3>Video playback</h3>
@ -216,23 +211,73 @@
<div class="row feature">
<div class="col-12 col-md-8 feature-image">
<img src="assets/filters.png" style="width: 100%">
</div>
<div class="col">
<h3>Local filters</h3>
Rich filter panel, where you can further filter your directory or search results.
</div>
</div>
<div class="row feature">
<div class="col-12 col-md-8 feature-image">
<img src="assets/blog.png" style="width: 100%">
</div>
<div class="col">
<h3>Blog</h3>
You can add *.md files to your directory and app will show them.
You can tag section in the *.md files with <code class="code-block">&lt;!-- @pg-date &lt;ISO_DATE> --></code>,
like: <code class="code-block">&lt;!-- @pg-date 2015-06-29 --></code> to attach them to a date.
Then, if you group by date, they will show up at the assigned day.
</div>
</div>
<div class="row feature">
<div class="col-12 col-md-8 feature-image">
<img src="assets/albums.png" style="width: 100%">
</div>
<div class="col">
<h3>Logical Albums</h3>
You can create logical albums (a.k.a.: Saved search) from any search query.
Current limitation: It is not possible to create albums from a manually picked photos.
</div>
</div>
<div class="row feature">
<div class="col-12 col-md-8 feature-image">
<img src="assets/faces.png" style="width: 100%">
</div>
<div class="col">
<h3>Faces</h3>
PiGallery2 can read face reagions from photo metadata.
Current limitation: No ML-based, automatic face detection.
</div>
</div>
<div class="row feature">
<div class="col-12 col-md-8 feature-image">
<img src="assets/random_link.png" style="width: 100%">
</div>
<div class="col">
<h3>Random link</h3>
You can create a link that will serve a random photo from your gallery.
You can use this link with 3rd party applications, like with an automatic wallpaper changer gadget.
</div>
<div class="col-12 col-md-8">
<img class="card-img-right" src="assets/random_link.jpg" style="width: 100%">
</div>
</div>
<div class="row feature">
<div class="col-12 col-md-8 order-last order-md-first">
<img class="card-img-right" src="assets/local_filters.jpg" style="width: 100%">
<div class="col-12 col-md-8 feature-image">
<img src="assets/settings.png" style="width: 100%">
</div>
<div class="col">
<h3>Local filters</h3>
Rich filter panel, where you can further filter your directory or search results.
<h3>Rich settings</h3>
PiGallery2 has a rich settings page where you can easily set up the gallery.
<a href="https://pigallery2.onrender.com/admin">Click here to see all the setting in the live demo.</a>
</div>
</div>
@ -283,23 +328,9 @@
<li>supports OSM and Mapbox by default, but you can add any provider that has a tile url</li>
</ul>
</li>
<li><strong>Two modes: SQL database and no-database mode</strong>
<li> Indexes Gallery to DB for a snappy user experience
<ul>
<li>both modes supports
<ul>
<li>user management</li>
<li>password protection can be disabled/enabled</li>
</ul>
</li>
<li>database mode supports:
<ul>
<li>faster directory listing</li>
<li>searching</li>
<li>instant search, auto complete</li>
<li>sharing</li>
<li>setting link expiration time</li>
</ul>
</li>
<li>Both MySQL and SQLite support</li>
</ul>
</li>
<li>Faces (persons) support
@ -330,6 +361,7 @@
<em>.ogv, </em>.webm files
</li>
<li>uses ffmpeg and ffprobe to generate video thumbnails</li>
<li>can transcode videos to mp4 for better support</li>
</ul>
</li>
<li>Markdown based blogging support
@ -337,11 +369,28 @@
<li>You can write some note in the *.md files for every directory</li>
</ul>
</li>
<li>job scheduling support, with the following supported task <a
href="https://github.com/bpatrik/pigallery2/issues/92">#92</a>
<ul>
<li>converting/transcoding videos</li>
<li>indexing db</li>
<li>etc..</li>
</ul>
</li>
<li>.pg2conf UI modifying files. <a
href="https://github.com/bpatrik/pigallery2/issues/177">#177</a>
<ul>
<li>List of these files are passed down to the UI modify its behaviour.</li>
<li>Currently, supported custom, per folder sorting.</li>
</ul>
</li>
<li>Dockerized</li>
</ul>
<hr/>
<p>Fork me on GitHub ribbon provided by <a href="https://github.com/simonwhitaker/github-fork-ribbon-css">simonwhitaker</a></p>
<p>Fork me on GitHub ribbon provided by <a href="https://github.com/simonwhitaker/github-fork-ribbon-css">simonwhitaker</a>
</p>
</main>

View File

@ -144,3 +144,7 @@ hr {
.banner-photo {
margin-bottom: 30px;
}
.row.feature:nth-child(odd) .feature-image{
order: 2;
}

View File

@ -0,0 +1,132 @@
/**
* These tests are only used for docs screenshot generation
*/
describe('Docs generation', () => {
beforeEach(() => {
cy.viewport(1600, 900);
cy.visit('/');
cy.get('.card-body');
cy.get('.col-sm-12').contains('Login');
/* ==== Generated with Cypress Studio ==== */
cy.get('#username').type('patrik');
cy.get('#password').clear();
cy.get('#password').type('vuc9ep');
cy.intercept({
method: 'Get',
url: '/pgapi/gallery/content/',
}).as('getContent');
cy.get('.col-sm-12 > .btn').click();
});
it.skip('Main page', () => {
cy.wait('@getContent');
cy.wait(1000);
cy.window().screenshot('main_page', {capture: 'viewport'});
});
it.skip('lightbox', () => {
cy.wait('@getContent');
cy.visit('/gallery/?p=IMG_4330.jpg');
cy.get('.photo-container > img[alt="IMG_4330.jpg"]', {timeout: 10000}); //the main photo should be visible
cy.get('div[title="info key: i"]').click();
cy.wait(1000);
cy.window().screenshot('lightbox', {capture: 'viewport'});
});
it.skip('Map', () => {
cy.wait('@getContent');
cy.get('app-gallery-map').click();
cy.wait(1000);
cy.get('div.leaflet-marker-icon span').contains('9').click({force: true});
cy.wait(500);
cy.get('img[src="/pgapi/gallery/content/./IMG_4303.jpg/icon"]').click();
cy.wait(1000);
cy.window().screenshot('map', {capture: 'viewport'});
});
it.skip('Search', () => {
cy.wait('@getContent');
cy.get('.search-text').type('2-km-from:"Puerto Rico" and be');
cy.wait(1000);
cy.window().screenshot('search', {clip: {x: 200, y: 0, width: 1600 * 2 / 3, height: 900 * 2 / 3}});
});
it.skip('Sharing', () => {
cy.wait('@getContent');
cy.get('app-gallery-share').click();
cy.wait(500);
cy.get('#getShareButton').click();
cy.wait(2000);
cy.get('#shareLink').clear({force: true}).type('https://<your domain>/share/c87dbe82', {force: true});
cy.wait(1000);
cy.window().screenshot('sharing', {capture: 'viewport'});
});
it.skip('filters', () => {
cy.wait('@getContent');
cy.get('app-gallery-navbar ng-icon[name="ionFunnelOutline"]').click({scrollBehavior: false});
cy.wait(1000);
cy.window().screenshot('filters', {capture: 'viewport'});
});
it.skip('video', () => {
cy.wait('@getContent');
cy.visit('/gallery/?p=trip_video.mp4');
cy.get('div[title="info key: i"]').click();
cy.get('#swipeable-container').click();
cy.get('.controls-video input.video-progress').invoke('val', 73.51484960779216)
.trigger('change');
cy.get('#swipeable-container').click();
cy.wait(1000);
cy.window().screenshot('video', {capture: 'viewport'});
});
it.skip('settings', () => {
cy.wait('@getContent');
cy.get('ng-icon[name="ionMenuOutline"]').click({scrollBehavior: false});
cy.get('ng-icon[name="ionSettingsOutline"]').click({scrollBehavior: false});
cy.wait(1000);
cy.get('#config-priority').click({force: true});
cy.get('button').contains('Advanced').click({force: true});
cy.wait(2000);
cy.get('.admin-menu button').contains('Photo').click({scrollBehavior: false});
cy.wait(1000);
cy.window().screenshot('settings', {capture: 'viewport'});
});
it.skip('albums', () => {
cy.intercept({
method: 'Get',
url: '/pgapi/albums',
}).as('getAlbums');
cy.visit('/albums');
cy.wait('@getAlbums');
cy.wait(1000);
cy.window().screenshot('albums', {clip: {x: 0, y: 0, width: 1600 * 2 / 3, height: 900 * 2 / 3}});
});
it.skip('faces', () => {
cy.intercept({
method: 'Get',
url: '/pgapi/person',
}).as('getFaces');
cy.visit('/faces');
cy.wait('@getFaces');
cy.wait(1000);
cy.window().screenshot('faces', {clip: {x: 0, y: 0, width: 1600 * 2 / 3, height: 900 * 2 / 3}});
});
it.skip('random link', () => {
cy.wait('@getContent');
cy.get('ng-icon[name="ionMenuOutline"]').click({scrollBehavior: false});
cy.get('ng-icon[name="ionHammerOutline"]').click({scrollBehavior: false});
cy.get('ng-icon[name="ionShuffleOutline"]').click({scrollBehavior: false});
cy.get('#randomLink').clear({force: true}).type('https://<your domain>/pgapi/gallery/random/{{}"type":1,"list":[{{}"type":104,"text":"Landscape","matchType":1},{{}"type":100,"text":"vuk"}]}', {
force: true,
scrollBehavior: false
});
cy.get('.modal-dialog .search-text').type('keyword:"Landscape" and vuk', {scrollBehavior: false});
cy.wait(1000);
cy.window().screenshot('random_link', {capture: 'viewport'});
});
it.skip('blog', () => {
cy.wait('@getContent');
cy.wait(1000);
cy.get('app-gallery-blog .btn-blog-details').click({multiple: true, scrollBehavior: false, force: true});
cy.window().screenshot('blog', {capture: 'viewport'});
});
});