S3D Player: private picture gallery on your web hosting
=======================================================

This package lets S3D Player users view your 3D photos and pictures in the
Media Manager by user name and password. Each gallery is a folder on your
hosting. You decide who sees which galleries and who may save pictures.
A dedicated server is not needed.

Files
-----
  config.php   your settings (the only file you need to edit)
  list.php     picture list of a gallery for the player (login and password)
  get.php      sends one picture (login and password on every file)
  admin.php    admin panel: users, galleries, statistics (rename it, step 4)
  common.php   common functions (internal)
  hash.php     password hash from the console (optional)
  .htaccess    closes pictures and internal files from the web
  galleries/   one subfolder per gallery (closed from the web)
  private/     service data: log, users, admin password hash (closed)

Two demo galleries are included: galleries/mix1 and galleries/mix2.

Requirements
------------
  * Web hosting with Apache 2.4 (.htaccess enabled) and HTTPS
  * PHP 7.3 or newer

Step 1. Upload the package
--------------------------
Copy all files and folders of this package into a folder on your hosting,
for example
  https://example.com/imgshow/
Make sure the .htaccess files are uploaded too (some FTP clients hide files
starting with a dot): one in the package folder, one in galleries/ and one
in private/.

Step 2. Create galleries
------------------------
Create a subfolder in galleries/ for every gallery and put the pictures in
it, for example galleries/holiday/. The folder name is the gallery name:
letters, digits, "_", "." and "-". Subfolders inside a gallery are not
shown; make them separate galleries instead.

Formats: jpg, jpeg, jfif, png, bmp, webp, gif, avif, jps, and the stereo
formats mpo (3D cameras) and heic/heif (3D photos from phones). The list
of extensions is $S3D_EXT in config.php.

The player detects the 3D layout of a picture from the file name, for
example "photo_x.jpg" or "photo sbs.jpg"; pictures without a mark are
checked by the player's format detector.

Step 3. Edit config.php
-----------------------
  S3D_ADMIN_PASS   admin password for the first login
  S3D_ADMIN_FILE   admin page file name, see step 4
  S3D_FILES        only if the galleries are not in galleries/

Leave the other values as they are.

Step 4. Admin panel
-------------------
Invent your own file name for the admin page, for example
"panel-7k2x.php" (letters, digits, "_" and "-", at least 6 characters).
Rename admin.php to this name and write the same name in S3D_ADMIN_FILE.
Under any other name, including admin.php, the page answers 404: this
hides it from people who scan sites for admin pages.

Open https://example.com/imgshow/panel-7k2x.php and log in with
S3D_ADMIN_PASS. Then:
  * check the "Server check" block: galleries found, number of pictures,
    and that the folders are writable
  * set a new admin password (section "Admin password")
  * add users with passwords; choose "view only" or "save allowed" and
    the galleries: "*" for all, or names like "mix1,holiday"
  * delete or disable the demo user "demo-user" (password 12345)

"access on/off" blocks a user at once: every picture is checked with the
password. The panel also shows all pictures, which galleries each user
opened and failed logins by IP.

"Sent" counts transfers: the player loads a picture for its preview card
and again for the show, and preloads the next pictures. It is not a count
of views by a person.

Forgot the admin password: delete private/admin.json via FTP; the password
from S3D_ADMIN_PASS works again.

Step 5. Test the server
-----------------------
In the Windows command prompt (replace the address, gallery, user and
password):

  curl -i -X POST -d "user=demo-user&pass=12345" "https://example.com/imgshow/list.php?dir=mix1"

  200 and "#private" on the first line   the server works
  403                                     wrong user or password, or not HTTPS
  404                                     no such gallery, or not allowed for this user
  429                                     too many wrong passwords, wait 15 min

Step 6. Add a gallery to S3D Player
-----------------------------------
In S3D Player open the Media Manager (Catalog button), click "User" and add
one section per gallery:

  [My gallery: Mix1]
  images   = https://example.com/imgshow/list.php?dir=mix1
  user     = demo-user
  password = 12345

Save the file, select the gallery and click "Rescan".
Optional: "save_dir = D:\Photo\Saved" sets where saved pictures go.

How it works
------------
  * list.php checks the password and the gallery and returns the list of
    pictures with permanent links to get.php. The player keeps the list in
    its cache; it never expires.
  * get.php checks the password and the gallery again for every picture.
    Pictures cannot be opened directly: .htaccess closes them.
  * "#save 1" in the list enables the Save option in the player for this
    user. Anyone who can view a picture can technically copy it; this is
    not DRM.

Service data (private/)
-----------------------
  access.log    log of logins, galleries, pictures sent and errors
  users.json    users (after the first change in the admin panel)
  admin.json    admin password hash
  fail_*.txt    failed login counters
All files are created with open permissions, so you can edit or delete
them by FTP. The folder is closed from the web by its .htaccess.

Troubleshooting
---------------
  Admin page answers 404
      the file name and S3D_ADMIN_FILE differ, or S3D_ADMIN_FILE is empty
  list.php answers 403 with the right password
      the site is opened by http, not https
  list.php answers 404
      the gallery folder does not exist, its name has other characters,
      or the user's galleries do not include it
  The gallery is empty in the player
      no pictures in the folder, or the extension is not in $S3D_EXT
  Pictures open directly by URL
      a .htaccess file is missing, or Apache ignores .htaccess
      (AllowOverride): ask the hosting support

Copyright (c) S3D Singapore, 2026 https://gradient-sg.com
