/Thrixty

360° Photography Player

Primary LanguageJavaScriptGNU General Public License v3.0GPL-3.0

Thrixty

360° Photography Player

Version: 2.3 | 22.09.2016

ToC:

1.) Thrixty Player

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

2.) Example

To view an example, download both this and the example repository.
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.

Keboard:
(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 Speed
[Arrow Down] => Decrease Speed
[G] => Zoom on/off
[F] => Fullscreen on/off
[ESC] => Stop Zoom, Rotation, Fullscreen all at once.

4.) Installation Tutorial

In this example we are using the index.html as a substitute for whatever you are using to generate the HTML.

  • Create an "index.html" in your websites root folder.

  • If you want to customize the players look, also create a "thrixty_custom.css" here.

  • Create a directory named "thrixty".

  • Extract this repository into "thrixty".

    • The files "LICENSE", "README.md" and "options_list.html" are not needed and can be deleted.

  • Create a directory "360_objects".

    • This folder is where you are gonna put all your objects.
    • For example purposes download and extract the Thrixty_example and move the contents of the "360_objects" folder into this one.
    • When using the 360Shots Software to generate the files, you should only copy and paste the object folder; ignore the rest of the files!

  • Your final folder structure should look like this:

     [website-mainfolder of your.domain.com]/
 |- [index.html]
 |- [thrixty_custom.css]
 |- thrixty/
 |  |- thrixty.js
 |  |- thrixty.css
 |- 360_objects/
 |  |- example/
 |  |  |- large/
 |  |  |  |- Filelist.txt
 |  |  |  |- [lots_of_large_images.jpg]
 |  |  |- small/
 |  |  |  |- Filelist.txt
 |  |  |  |- [lots_of_small_images.jpg]

  • 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>
 	</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 dont.
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!
Its easier to detect and solve those problems by using your browsers developer tools.
  • Look into your console and files sections for any files not being loaded.
  • Look into the global object "Thrixty" and read the log. (Thrixty.logs)
    • What is the last action in main_log?
    • Are there any player_logs?
    • Was the first small image loaded?

Are you using Wordpress?

Look at our Wordpress Plugin!

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):

Version 2.3
option Description possible values
thrixty-basepath These are telling the game where to find the Filelists.
"[http://basepath][filelist-path-small.txt]"
"[http://basepath][filelist-path-large.txt]"
 [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-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-pointer How to point to the zoomed in position. minimap, marker, none
thrixty-outbox-position Where the zoom box should spawn. right, bottom, left, top
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, what Thrixty is doing:

  • 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

  • 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  F.Heitmann @ 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/>.