Thrixty

360° Photography Player

Version: 3.2 | Apr 26, 2022

ToC:

1.: Thrixty Player
2.: Example
3.: Usage
4.: Installation Tutorial
5.: Filelists
6.: Parameters
7.: Customization
8.: General Description
9.: Documentation
10.: Change Log
11.: Planned Features and Changes
12.: License

1.) Thrixty Player

The Thrixty Player is a tool to show off your 360° Photography.
It uses HTML5 CANVAS to display sequences.

2.) Example

As an example, we have included the ./example folder.
Unzip this repository into the 'thrixty' folder of the example and start up the 'index.html'.

3.) Usage

Mouse/Touch:

[Click/Tap](single) => Play/Pause
[Click/Tap](double) => Zoom on/off
[Drag/Swipe] => Stop automatic rotation and turn the object. Also works in Zoom mode. | Drag the marker or minimap in classic mode to move the expanded area.

Keyboard:
(To use these, the player needs to be focused - click once inside the player.)

[Spacebar] => Play/Pause
[Arrow Left] => Step Backward
[Arrow Right] => Step Forward
[Arrow Up] => Increase Rotation Speed
[Arrow Down] => Decrease Rotation Speed
[G] => Zoom on/off
[F] => Fullscreen on/off
[ESC] => Stop Zoom, Rotation, Fullscreen all at once.

4.) Installation Tutorial

-- UNDER CONSTRUCTION --

[...]

Install Node.js and npm.
Open a terminal in an empty folder and enter the following commands:

npm i thrixty
cd ./node_modules/thrixty
npm run build

Congratulations, you have transpiled the output file ./node_modules/thrixty/thrixty/thrixty.js. Now to run a webserver (optional; allows you to test the program):

node app.js

Open "localhost:3000/index.html" in your browser and admire the view!
Once you wish to terminate the webserver, press Ctrl + C in the terminal.

[...]

When using the 360Shots Software to generate the files, you should only copy and paste the object folder; ignore the rest of the files!

[...]

For the Player to be able to do anything, you need to include both "thrixty.js" and "thrixty.css" in the DOM.
For semantics you should put it into the head-section.
When you choose to include a "thrixty_custom.css", include it after both "thrixty.js" and "thrixty.css"!

Now create a div somewhere in the body with 'class="thrixty"' as seen in the following example.

The HTML-attribute "thrixty-basepath" is one of the options, referencing the basepath for the Filelists.
The Player will be generated into each of these divs, while using the corresponding attributes as parameters.

 <!DOCTYPE html>
 <html>
 	<head>
 		<script type="text/javascript" src="thrixty/thrixty.js"></script>
 		<link type="text/css" rel="stylesheet" href="thrixty/thrixty.css">
 		<!-- uncomment the following line, when customizing the player -->
 		<!--<link type="text/css" rel="stylesheet" href="/thrixty_custom.css">-->
 	</head>
 	<body>
 		<div class="thrixty"
 			thrixty-basepath="360_objects/example/"
 		></div>
 		<canvas id="thrixty_zoom_canvas_1" class="thrixty_zoom_canvas">
 	</body>
 </html>

This tutorial neglects the possible need for absolute paths.
- Depending on your server configuration and your path to that 'index.html' you may find relative paths to be wrong.
- When dealing with websites you absolutely need to know about relative and absolute paths anyway. Please educate yourself, if you don't.

When encountering a problem, check the following points in the given order:

Read the documentation...
Was "thrixty.js" found and loaded? (path incorrect?; resource not accessible?)
Was "thrixty.css" found and loaded? (path incorrect?; resource not accessible?)
Was "thrixty_custom.css" found and loaded if needed?
Was the div written properly?
- Properly labeled with class="thrixty"?
- Have you set the "tabindex"-attribute without using the same value multiple times?
- Have you set the parameters (like "thrixty-basepath", "thrixty-filelist-path-small" or "thrixty-filelist-path-large") correctly?
Were the Filelists found and loaded? (path incorrect?; resource not accessible?)
Were the images referenced in the filelists found and loaded? Especially the first small image is critical!

5.) Filelists

Filelists are text documents that are referencing to the images used for the animation.
They consist of a comma-seperated list of paths.

Thrixty currently uses two Filelists - a small and a large one.
They are referenced in the "thrixty-filelist-path-small" and "thrixty-filelist-path-large" settings respectively.
The part of the path they both share is referenced in the basepath.

Therefore these settings:

basepath = http://www.example.com/
filelist-path-small = small/Filelist.txt
filelist-path-large = large/Filelist.txt

would make Thrixty look for these paths:

small:  http://www.example.com/small/Filelist.txt
large:  http://www.example.com/large/Filelist.txt

6.) Parameters

Here is a list of the usable params (in the form of HTML-attributes):

option	Description	possible values
Version 2.3
thrixty-basepath	These are telling the player where to find the Filelists. "[http://basepath][filelist-path-small.txt]" "[http://basepath][filelist-path-large.txt]"	[empty], [mainpath]
thrixty-basepath		Location of localization (text) file. The default is "./thrixty/text.json".	[empty], [mainpath]
thrixty-filelist-path-small			small/Filelist.txt, [subpath]
thrixty-filelist-path-large	large/Filelist.txt, [subpath]
thrixty-play-direction	The direction the object is turning in automatic rotation.	normal, reverse[d]
thrixty-drag-direction	The direction the object is turning when dragging it.	normal, reverse[d]
thrixty-autoload	When autoload is on, it will automatically start loading all images, when ready. When off, a load-button will be shown. Will always be off on mobile devies (decided on user-agent).	on / 1, off / 0
thrixty-autoplay	When autoplay is on, the animation will start playing as soon as all images were loaded. When off, nothing happens.	on / 1, off / 0
thrixty-start-image-id	ID of image that the animation is meant to start with.	0, [integer]
thrixty-cycle-duration	Duration of each whole turn in seconds.	5, [integer]
thrixty-zoom-control	How to move the zoomed image. Automatically use the mouseposition or drag the cutout.	progressive, classic
thrixty-zoom-mode	Zoomed in images showing in the same or an extra window.	inbox, outbox, none
thrixty-zoom-mode-mobile	Zoomed in images showing in the same or an extra window on mobile devices.	inbox, outbox, none
thrixty-zoom-pointer	How to point to the zoomed in position.	minimap, marker, none
thrixty-marker-mode	How the marker size should be calculated (old version was kept for compability).	new, old
thrixty-sensitivity-x	How sensitive the Player will react horizontally to touch gestures. The finger needs to be move at least X pixel.	20, [integer]

7.) Customization

Customization of the player is quite easy, as Thrixty is optimised for doing as much as possible over HTML and CSS.
The following examples are showing you some possibilities:

Create the file "thrixty_custom.css" and include it after the initialization file, if not already done.
To give the Player a maximum height of 500 px, include the following CSS code into the file:
```
 div[thrixty=found]{
 	max-height: 500px;
 }
```
To have an orange border around the object, include the following CSS code into the file:
```
 div[thrixty=found] #canvas_container{
 	border: 2px solid orange;
 }
```
To have a blue background on the controls container, include the following CSS code into the file:
```
 div[thrixty=found] .control_container_one{
 	background: blue;
 }
```
To hide the Zoom Button as long as it is disabled, include the following CSS code into the file:
```
 div[thrixty=found] #zoom_btn:disabled{
 	display: none;
 }
```

8.) General Description

A short explanation of what Thrixty does:

After including and interpreting the JS, create namespace "Thrixty" and wait for the site to finish loading.
Look for all divs with a class of "thrixty" ("div.thrixty").
Initialize a Player instance for each div found.
- Parse (and check) options, load the filelists
- Parse filelists, cache images, generate HTML and display the first image while loading.
- Set the attribute "thrixty" to "found".
- Wait for user input.

9.) Documentation

You are looking at it...

10.) Change Log

V3:
- [See the separate changelog.]
V2:
- V2.3:
  - Fixed left and right arrows.
  - Improvements in documentation.
  - Improvements to "filelist-reversion".
    - Split up into two params "thrixty-play-direction" and "thrixty-drag-direction".
    - play-direction is the direction the object will turn during automatic turns.
    - drag-direction is the direction the object will turn when dragging the object.
- V2.2.2:
  - Bugfix resizing
- V2.2.1:
  - Fix of incorrect use of redraw throttle.
- V2.2:
  - Holding next and previous button rotates the image.
    - The speed is fixed for now.
  - Tried to implement an SVG Sprite.
    - The "use"-Tag is not widely supported on mobile browsers (they are being stupid again...).
    - Therefore the code for the SVG-Icons is now saved in the Thrixty namespace (Thrixty.icons) and is being used to write the SVGs right into the HTML.
    - SVG Icons are styled by CSS.
  - Fixed logging and Safari's filelist parsing.
  - Renamed "state"-attributes on buttons to "thrixty-state".
- V2.1:
  - Now respects max-width and max-height on the main div.
    - The main div still needs to set the style tag, so do this over CSS-Selectors!
    - Included a custom CSS example into the Readme.
  - Improvement of filelist parse.
- V2.0.1:
  - Hotfix: Error with Whitespaces
- V2.0.0:
  - Throttled redraw.
  - Player only reacts to mouseposition, when pointing inside.
  - Implemented a rudimentary destructor.
  - Changed the css to select player instances by custom attribute instead of by class.
  - Use large images in Fullpage Mode.
  - Cleaned up the code.
  - Adjusted behavior when images werent found. (small instead of large, blank instead of small)
  - When the sizing image (first in small filelist) couldnt be loaded, nothing will be displayed. In earlier versions the player was still showing the controls.
  - General performance improvements by adding throttle and debounce to bottleneck events.
  - Bugfix: Autoplay Off also triggered Autoload Off
  - Renamed option: position-indicator => zoom-pointer
  - Renamed option: direction => reversion
  - Class restructuring.
    - Joined MainClass, EventHandler and DrawingHandler into a single Player class.
    - Renamed Namespace from "ThrixtyPlayer" to "Thrixty".
  - Gotten rid of jQuery.
V1:
- V1.6.1:
  - Path-handling improved.
  - The basepath is now initially empty.
    Therefore the path to the small filelist would be "[current_page/]small/Filelist.txt", when no params were set.
  - Standard values for filelist settings: "small/Filelist.txt" and "large/Filelist.txt".
    These paths are the ones generated by our 360 Shots Worktable Suite.
- V1.6:
  - New option "Autoload " can be used to restrict the player from automatically loading. Autoload is always disabled on mobile devices!
  - Animation Speed Modifier reworked. Now has a list of speeds you can switch through by pressing arrow up/down.
  - Changed effects of "direction" option. Will now simply reverse the filelist before load, instead of fuzzy logic.
  - Renamed "seconds-per-turn" to "cycle-duration".
- V1.5.1:
  - Fullpage disabled on mobile devices - it is not working properly on those small screens (and actually unneccessary).
- V1.5:
  - Allowed double-finger-zoom, when touching with both fingers at the same time.
    This cannot be made more intuitive, as there are issues with non-conventional event uses. (look previous)
  - Browser-developers are not able to follow conventions or standards.
    Thus positions and sizes are now calculated instead of declarated.
  - Included information for developers into the Readme. Especially for the namespace object "ThrixtyPlayer".
  - Moved version number into the ThrixtyPlayer Object.
  - Implemented a parameter for Autoplay: "thrixty-autoplay".
  - Load-Button now stays hidden, until the preview image becomes visible.
  - Improved Readme with a section on parameters.
- V1.4:
  - Rewrote Event Handler.
  - Fixed iPad Support. (maybe other mobile browsers are still broken...)
  - Changed folder structure.
  - Saving bandwidth on mobile devices (detected by user-agent) by showing a load button instead of auto loading.
  - Changes in state management.
  - Zoom Mode can now be "none" for disabling zoom.
    (Will automatically trigger, when large filelist was not found.)
  - Rebuilt Autostart.
  - Let the Player log into an object. (Spamming Console Log is annoying...)
  - Introduced a log-object in Namespace. ('console.log(ThrixtyPlayer.logs);')
  - Rebuilt the initialize functionality.
  - Path- and file-name conventions.
  - Reinforced compatibility on windows systems.
  - Enforced strict-mode.
- V1.3.1:
  - Fixed Fullpage Mode.
- V1.3:
  - Re-encoding of line-endings to windows format.
  - Safari drawing error resolved.
  - Rewritten DrawingHandler.
  - Full-page mostly fixed.
    To fix this completely will be the first thing to do in Version 1.4.
  - Split up the param "zoom-mode" into "zoom-mode", "zoom-control" and "position-indicator".
  - Prepended semicolons.
- V1.2:
  - Introduced the new position indicator "marker" and made the "minimap" look less grabbable
  - New options "zoom-control" and "outbox-position"
  - Splitted up the zoom options like "inbox_minimap" into seperate options
  - Changes in initialization
  - Removed Yoda-Conditions
  - Changes in Readme.md
- V1.1:
  - Changes in Error Handling and Reporting
- V1.0 (Release):
  - Play&Pause
  - Step forward
  - Step backward
  - Zoom
  - Fullscreen
  - Keyboard Shortcuts
  - Drag Rotation

11.) Planned Features and Changes (unordered & some may be discarded)

New Filelist Format (JSON-Style)
- Settings area to avoid the overload of html attributes.
- Support for Background Image with automatic scale detection. (Background Strategies like "always filled", "stretch", etc.)
- Image Layers (for inside or top-down views of the same object)
Improvements in Touch Zooming
- Continuous zoom. (Think about a concept, to make this easily usable with touch gestures. In the end, there already is a great zoom function on most phones.)
  - Maybe a detection of resolution can be useful?
- Fix the way, multi-fingered touch events work currently. (Should they be used anyway? Maybe just ignore any events with multiple fingers?)
Context menu.
- HTML5 Contextmenus are awesome!
- User settings
  - Intented for Users to select zoom-style, design etc..
  - Is thought of to be designed like an extra window.
  - Options in select boxes(?).
- Log Export to make it easier for users to report errors.
- Rotation speed selection
  - Button holding rotation speed should be dependant on the current speed.
README improvements:
- Add detailed information about filelists and their purpose.
- Add a concept describing picture.
  - Notation: ![alt_text](image/path.png)
- Add a proper example for player customization (look changes & icon replacement).
- Proofread.
Loading state should be visible to CSS, in case smt happens with the animation.
- Also every load should be aborted, when some core function failed.
- This could also be improved by implementing a replace picture, that is being showed instead of an animation, when something failed.
When using a Shortcut, show an icon of the associated function with a fast little flash effect. (Inspiration: Youtube)
Log amount of found images.

12.) License

Thrixty Player Copyright (C) 2015-2022 Fuchs EDV GmbH for 360Shots

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

Name		Name	Last commit message	Last commit date
Latest commit History 138 Commits
example		example
src		src
thrixty		thrixty
CHANGELOG		CHANGELOG
LICENSE		LICENSE
README.md		README.md
app.js		app.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
webpack.config.ts		webpack.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Thrixty

1.) Thrixty Player

2.) Example

3.) Usage

4.) Installation Tutorial

When encountering a problem, check the following points in the given order:

5.) Filelists

6.) Parameters

7.) Customization

8.) General Description

9.) Documentation

10.) Change Log

11.) Planned Features and Changes (unordered & some may be discarded)

12.) License

About

Releases

Packages

Languages

License

FuchsEDV/Thrixty

Folders and files

Latest commit

History

Repository files navigation

Thrixty

1.) Thrixty Player

2.) Example

3.) Usage

4.) Installation Tutorial

When encountering a problem, check the following points in the given order:

5.) Filelists

6.) Parameters

7.) Customization

8.) General Description

9.) Documentation

10.) Change Log

11.) Planned Features and Changes (unordered & some may be discarded)

12.) License

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages