diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..b06acbd --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1 @@ +ko_fi: mpetroff diff --git a/.gitignore b/.gitignore index 0194eed..0f16a6b 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,9 @@ utils/doc/generated_docs # Ignore IntelliJ Files .idea + +# Ignore logs +tests/*.log + +# Ignore tests +tests/** \ No newline at end of file diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..328155d --- /dev/null +++ b/.travis.yml @@ -0,0 +1,13 @@ +language: generic +dist: xenial +addons: + sauce_connect: true +before_install: + - sudo apt-get install -y python3-pillow python3-numpy python3-pip + - sudo pip3 install selenium +jobs: + include: + - stage: build + script: python3 utils/build/build.py + - stage: test + script: python3 tests/run_tests.py diff --git a/COPYING b/COPYING index 624d9c7..2e8e824 100644 --- a/COPYING +++ b/COPYING @@ -1,4 +1,4 @@ -Copyright (c) 2011-2018 Matthew Petroff +Copyright (c) 2011-2019 Matthew Petroff Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in diff --git a/VERSION b/VERSION index 005119b..f225a78 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.4.1 +2.5.2 diff --git a/changelog.md b/changelog.md index 1730ba6..90678cf 100644 --- a/changelog.md +++ b/changelog.md @@ -2,8 +2,68 @@ Changelog ========= -Changes in Pannellum 2.4.1 --------------------------- +Changes in Pannellum 2.5.2 (2019-07-13) +--------------------------------------- + +Bugfixes: + - Fixed regression in Video.js plugin + + +Changes in Pannellum 2.5.1 (2019-07-13) +--------------------------------------- + +Other: + - Fixed issue with tagging 2.5.0 release + + +Changes in Pannellum 2.5.0 (2019-07-13) +--------------------------------------- + +New Features: + - The background color can be set for partial panoramas + (`backgroundColor` parameter) + - Partial panoramas are now supported for the multiresolution format + - An author URL can now be added (`authorURL` parameter) + +New API functions: + - Added `fullscreenchange`, `zoomchange`, and `animatefinished` events + - Added `stopMovement` function for stopping all viewer movement + +Improvements: + - Equirectangular images are now automatically split into two separate + textures if they're too big (images up to 8192px wide should now be + widely supported) + - Improved render quality for equirectangular images on mobile (using `highp` + for fragment shader) + - Keyboard events for keys not used by the viewer are no longer captured, and + the list of captured keys is configurable (`capturedKeyNumbers` parameter) + - Multiresolution tiles can now be generated from cylindrical panoramas + - Hot spots can now be removed from scenes that aren't currently loaded + - Hot spot cursor is now set via CSS class (so it can be overridden) + - Hot spot link attributes can now be set (`attributes` parameter) + - The "friction" that slows down the viewer motion can now be configured + (`friction` parameter) + - Dynamic scenes are now properly supported for tours + +Bugfixes: + - Fixed regression in fallback renderer + - Fixed bug with URL encoding + - Fixed regression in Video.js plugin + - Fixed auto-rotate bug that was manifested when using API to set view + - Fixed full screen bug in Chrome + - Fixed bug with removing event listeners + - Fixed issue with mouse dragging causing jump around yaw limits + - Fixed bug with deleting hot spots + - Fixed bug with fading between scenes + +Other: + - Added limited test suite / continuous integration + - Removed `requestAnimationFrame` shim, dropping support for some + older browsers + + +Changes in Pannellum 2.4.1 (2018-03-03) +--------------------------------------- Bugfixes: @@ -11,8 +71,8 @@ Bugfixes: - The API's `loadScene` method now works when no scenes have been loaded yet -Changes in Pannellum 2.4.0 --------------------------- +Changes in Pannellum 2.4.0 (2018-01-30) +--------------------------------------- New Features: @@ -77,16 +137,16 @@ Bugfixes: - Fixed bug related to removing hot spots -Changes in Pannellum 2.3.2 --------------------------- +Changes in Pannellum 2.3.2 (2016-11-20) +--------------------------------------- Bugfixes: - Fix Chrome fullscreen regression introduced in 2.3.1 -Changes in Pannellum 2.3.1 --------------------------- +Changes in Pannellum 2.3.1 (2016-11-19) +--------------------------------------- Bugfixes: @@ -99,8 +159,8 @@ Improvements: - Better handling of view limits when both limits are in view -Changes in Pannellum 2.3.0 --------------------------- +Changes in Pannellum 2.3.0 (2016-10-30) +--------------------------------------- New Features: @@ -169,8 +229,8 @@ Backwards-Incompatible Configuration Parameter Changes: can be used with the `config` parameter -Changes in Pannellum 2.2.1 --------------------------- +Changes in Pannellum 2.2.1 (2016-03-11) +--------------------------------------- New Features: @@ -183,8 +243,8 @@ Improvements: - Better restriction on yaw range -Changes in Pannellum 2.2.0 --------------------------- +Changes in Pannellum 2.2.0 (2016-01-27) +--------------------------------------- New Features: @@ -251,15 +311,15 @@ Other: - Added JSDoc documentation -Changes in Pannellum 2.1.1 --------------------------- +Changes in Pannellum 2.1.1 (2015-01-19) +--------------------------------------- Bugfixes: - Force subpixel rendering for hot spots -Changes in Pannellum 2.1.0 --------------------------- +Changes in Pannellum 2.1.0 (2015-01-14) +--------------------------------------- New Features: @@ -301,15 +361,15 @@ Other: removed -Changes in Pannellum 2.0.1 --------------------------- +Changes in Pannellum 2.0.1 (2014-08-24) +--------------------------------------- Bugfixes: - Fix keyboard controls in Safari -Changes in Pannellum 2.0 ------------------------- +Changes in Pannellum 2.0 (2014-08-22) +------------------------------------- New Features: @@ -334,8 +394,8 @@ Bugfixes: - Numerous -Changes in Pannellum 1.2 ------------------------- +Changes in Pannellum 1.2 (2012-08-28) +------------------------------------- New Features: diff --git a/doc/json-config-parameters.md b/doc/json-config-parameters.md index 7f872ea..796bee6 100644 --- a/doc/json-config-parameters.md +++ b/doc/json-config-parameters.md @@ -23,6 +23,13 @@ If set, the value is displayed as the panorama's author. If no author is desired, don't set this parameter. +### `authorURL` (string) + +If set, the displayed author text is hyperlinked to this URL. If no author URL +is desired, don't set this parameter. The `author` parameter must also be set +for this parameter to have an effect. + + ### `strings` (dictionary) Allows user-facing strings to be changed / translated. @@ -52,7 +59,8 @@ counter-clockwise, and negative is clockwise. Sets the delay, in milliseconds, to start automatically rotating the panorama after user activity ceases. This parameter only has an effect if the -`autoRotate` parameter is set. +`autoRotate` parameter is set. Before starting rotation, the viewer is panned +to the initial pitch. ### `autoRotateStopDelay` (number) @@ -308,6 +316,13 @@ If `clickHandlerFunc` is specified, this function is added as an event handler for the hot spot's `click` event. The event object and the contents of `clickHandlerArgs` are passed to the function as arguments. +#### `scale` (boolean) + +When `true`, the hot spot is scaled to match changes in the field of view, +relative to the initial field of view. Note that this does not account for +changes in local image scale that occur due to distortions within the viewport. +Defaults to `false`. + ### `hotSpotDebug` (boolean) When `true`, the mouse pointer's pitch and yaw are logged to the console when diff --git a/package.json b/package.json index 2098676..f0712e4 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "pannellum", "description": "Pannellum is a lightweight, free, and open source panorama viewer for the web.", - "version": "2.4.1", + "version": "2.5.2", "bugs": { "url": "https://github.com/mpetroff/pannellum/issues" }, diff --git a/paper/paper.bib b/paper/paper.bib new file mode 100644 index 0000000..7a454f4 --- /dev/null +++ b/paper/paper.bib @@ -0,0 +1,100 @@ +@inproceedings{Chen1995, + doi = {10.1145/218380.218395}, + year = {1995}, + publisher = {{ACM} Press}, + author = {Shenchang Eric Chen}, + title = {{QuickTime} {VR}}, + editor = {Susan G. Mair and Robert Cook}, + booktitle = {Proceedings of the 22nd annual conference on computer graphics and interactive techniques ({SIGGRAPH} '95)}, +} + +@inproceedings{Gede2015, + author = {M\'{a}ty\'{a}s Gede and Zsuzsanna Ungv\'{a}ri and Klaudia Kiss and G\'{a}bor Nagy}, + title = {Open-source web-based viewer application for {TLS} surveys in caves}, + booktitle = "Proceedings of the 1st {ICA} {European} Symposium on Cartography ({EuroCarto} 2015)", + year = {2015}, + editor = {Georg Gartner and Haosheng Huang}, + pages = {321--328}, + url = {https://cartography.tuwien.ac.at/eurocarto/wp-content/uploads/2015/10/6-7.pdf}, + urldate = {2019-07-14}, + isbn = {9781907075032}, +} + +@article{Srinivasan2018, + doi = {10.23925/1980-7651.2018v21;p71-83}, + year = {2018}, + month = jun, + publisher = {Portal de Revistas {PUC} {SP}}, + volume = {21}, + pages = {71}, + author = {Venkat Srinivasan and T.B. Dinesh and Bhanu Prakash and A. Shalini}, + title = {Thirteen ways of looking at institutional history: a model for digital exhibitions from science archives}, + journal = {Circumscribere: International Journal for the History of Science}, +} + +@article{Herault2018, + doi = {10.1186/s40561-018-0074-x}, + year = {2018}, + month = oct, + publisher = {Springer Nature}, + volume = {5}, + number = {1}, + author = {Romain Christian Herault and Alisa Lincke and Marcelo Milrad and Elin-Sofie Forsg\"{a}rde and Carina Elmqvist}, + title = {Using 360-degrees interactive videos in patient trauma treatment education: design, development and evaluation aspects}, + journal = {Smart Learning Environments}, +} + +@incollection{Mohr2018, + doi = {10.1007/978-3-030-04028-4_71}, + year = {2018}, + publisher = {Springer International Publishing}, + pages = {613--620}, + author = {Fabian Mohr and Soenke Zehle and Michael Schmitz}, + editor = {Rebecca Rouse and Hartmut Koenitz and Mads Haahr}, + title = {From Co-Curation to Co-Creation: Users as Collective Authors of Archive-Based Cultural Heritage Narratives}, + booktitle = {Interactive Storytelling}, +} + +@inproceedings{Albrizio2013, + author = {Patrizia Albrizio and Francesco de Virgilio and Ginevra Panzarino and Enrica Zambetta}, + title = {WebGIS e divulgazione del dato archeologico con software open source. Il progetto ``Siponto Aperta''}, + booktitle = {Proceedings of {ArcheoFOSS}: free, libre and open source software e open format nei processi di ricerca archeologica}, + year = {2013}, + editor = {Filippo Stanco and Giovanni Gallo}, + pages = {101--114}, + edition = {8th}, + url = {https://www.archaeopress.com/ArchaeopressShop/Public/download.asp?id=%7B14C6CFBD-3371-4DF0-8971-D4ABC24E661E%7D}, + urldate = {2019-07-14}, + isbn = {9781784912598}, +} + +@online{ESO2017, + author = {{European Southern Observatory}}, + title = {A panorama view of the {VLT}}, + year = {2017}, + month = sep, + url = {https://www.eso.org/public/images/165309674464e758889a6_eq-ext/}, + urldate = {2019-07-14}, +} + +@techreport{WebGL, + author = {Dean Jackson}, + title = {{WebGL} Specification}, + month = oct, + url = {https://www.khronos.org/registry/webgl/specs/1.0.3/}, + urldate = {2019-07-14}, + year = {2014}, + type = {Khronos Specification}, + institution = {Khronos Group}, +} + +@techreport{Canvas, + author = {Rik Cabanier and Jatinder Mann and Jay Munro and Tom Wiltzius and Ian Hickson}, + title = {{HTML} Canvas {2D} Context}, + month = nov, + url = {https://www.w3.org/TR/2015/REC-2dcontext-20151119/}, + urldate = {2019-07-14}, + year = {2015}, + type = {{W3C} Recommendation}, + institution = {World Wide Web Consortium ({W3C})}, +} diff --git a/paper/paper.md b/paper/paper.md new file mode 100644 index 0000000..63d1dc0 --- /dev/null +++ b/paper/paper.md @@ -0,0 +1,62 @@ +--- +title: 'Pannellum: a lightweight web-based panorama viewer' +tags: + - panoramas + - visualization + - WebGL +authors: + - name: Matthew A. Petroff + orcid: 0000-0002-4436-4215 + affiliation: 1 +affiliations: + - name: Department of Physics & Astronomy, Johns Hopkins University, Baltimore, Maryland 21218, USA + index: 1 +date: 15 July 2019 +bibliography: paper.bib +--- + +# Summary + +_Pannellum_ is an interactive web browser-based panorama viewer written in +JavaScript and primarily based on the WebGL web standard [@WebGL] for graphics +processing unit (GPU)-accelerated rendering to the HTML5 ```` element +[@Canvas]. It supports the display of panoramic images that cover the full +sphere, or only parts of it, in equirectangular format, in cube map format, or +in a tiled format that encodes the panorama in multiple resolutions, which +allows for parts of the panorama to be dynamically loaded, reducing data +transfer requirements. In addition to single panoramas, multiple panoramas can +be linked together into a virtual tour, with navigation enabled via +"hot spots," which can also be used to add annotations. + +The display of interactive panoramic images on the web dates back to the +mid-1990s, with the development of Apple's QuickTime VR format and associated +web browser plug-ins [@Chen1995]. When development on _Pannellum_ started in +2011, WebGL was a nascent technology, and the majority of existing panorama +viewers for websites were then still based on Java or Adobe Flash plug-ins, +which had supplanted QuickTime as the technology of choice. Since then, both +the viewer and underlying technologies have matured immensely. + +An application programming interface (API) is provided, which allows external +code to control the viewer and implement features such as custom buttons or +integration with other web page elements, e.g., maps [@Gede2015; @Albrizio2013]. +Panoramic videos are supported via a bundled extension, which is built using +the API. The underlying rendering code is separate from the user interface +code, which allows for more extensive customization and tighter integration +with external code, if desired. This rendering code uses a pinhole camera model +for equirectangular panoramas implemented as a WebGL fragment shader, instead +of the more common---and less accurate---approach of mapping the panorama onto +a geometric approximation of a sphere. + +_Pannellum_ has proven useful in various fields, when the display of panoramic +images is needed to help digest or present information. These research +applications range from cartography [@Gede2015] to digital humanities +[@Srinivasan2018; @Mohr2018] to archaeology [@Albrizio2013] to medical +education [@Herault2018]. It has also found use in public outreach +applications, such as its use by the European Southern Observatory to display +panoramas of their observatories [@ESO2017]. _Pannellum_ is intended to be used +any time an interactive panorama needs to be displayed in a web page, be it an +internal research application or a publicly accessible website. It may also +work with certain mobile application frameworks, but such use is not officially +supported. + +# References diff --git a/readme.md b/readme.md index f3bcaf7..56e2799 100644 --- a/readme.md +++ b/readme.md @@ -1,8 +1,11 @@ # Pannellum +[![Build Status](https://travis-ci.org/mpetroff/pannellum.svg?branch=master)](https://travis-ci.org/mpetroff/pannellum) +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3334433.svg)](https://doi.org/10.5281/zenodo.3334433) + ## About -Pannellum is a lightweight, free, and open source panorama viewer for the web. Built using HTML5, CSS3, JavaScript, and WebGL, it is plug-in free. It can be deployed easily as a single file, just 15kB gzipped, and then embedded into pages as an `