Projects/Edu/KStars/SkyGuides: Difference between revisions

From KDE TechBase
< Projects‎ | Edu‎ | KStars
(Created page with "{{Construction}}")
 
No edit summary
Line 1: Line 1:
{{Construction}}
{{Construction}}
== Introduction ==
The SkyGuides feature enable users to create and view interactive sky tours for KStars.
'''Author:''' Marcos Cardinot <[email protected]> <br>
'''Source code:''' https://github.com/cardinot/kstars/tree/skyguide
== SkyGuide Tools ==
=== Opening ===
Both SkyGuide Viewer and SkyGuide Writer can be found on the Tools menu. In addition, they can be opened using the keyboard shortcuts <code>ctrl+k</code> and <code>ctrl+w</code> respectively.
[[File:Example.jpg]]
=== SkyGuide Viewer ===
The SkyGuide Viewer works like a browser and can be docked to the main KStars window.
[[File:Example.jpg]]
=== SkyGuide Writer ===
The SkyGuide Writer enables you to create or edit a SkyGuide.
[[File:Example.jpg]]
{{Remember|1=A SkyGuide should have a title, description and one slide at least.}}
== SkyGuide File ==
A SkyGuide is essentially a zip archive containing a JSON file that must be named as <code>guide.json</code> and the source images (if any).
{{Warning|1=The JSON file must be in the root of its zip archive.}}
=== JSON File ===
==== Fields ====
{| class="wikitable"
| rowspan="2" | ''Key''
| rowspan="2" | ''Type''
| colspan="2" style="text-align:center;" | ''Version''
| rowspan="2" | ''Description''
|-
| ''Tool''
| ''KStars'
|-
|formatVersion
|int
|1.0.0+
|master
|Format version
|-
|header
|Object
|1.0.0+
|master
|Header fields (order does not matter)
|-
|slides
|Array
|1.0.0+
|master
|Array of objects containing the information of each slide (order matter).
|-
|authors
|Array
|1.0.0+
|master
|Array of objects containing the information of each author (order matter).
|-
|creationDate
|String
|1.0.0+
|master
|The date of creation of its SkyGuide in "yyyy-mm-dd" format.
|-
|language
|String
|1.0.0+
|master
|The language of its SkyGuide.
|-
|centerPoint
|String
|1.0.0+
|master
|[optional] when this slide is open, select this sky object.
|-
|image
|String
|1.0.0+
|master
|[optional] path to an image that will be displayed on this slide.
|-
|skyDateTime
|String
|1.0.0+
|master
|[optional] when this slide is opened, changes the sky date!
|-
|zoomFactor
|Int
|1.0.0+
|master
|[optional] a number between 250 and 5000000.
|}
==== guides.json (1) ====
{
    "formatVersion": 1,
    "header": {
        "authors": [
            {
                "email": "String",
                "name": "String",
                "url": "String"
            }
        ],
        "creationDate": "2015-08-20",
        "description": "String",
        "language": "String",
        "title": "String",
        "version": 1
    },
    "slides": [
        {
            "title": "String",
            "text": "String",
            "centerPoint": "Sky Object",
            "image": "kstars.png",
            "skyDateTime": "",
            "zoomFactor": 0
        }
    ]
}
== Installing a SkyGuide ==
{{Remember|1=The installation directory must be writable!}}
=== GUI ===
* Open the SkyGuide Viewer tool
* Click on the 'Install' button on the lower toolbar
* Select the guide file (zip archive)
=== Manually ===
* Go to the installation directory
* Extract your SkyGuide (zip archive) on the <code>tools/skyguide/resources/guides</code> directory

Revision as of 22:39, 23 August 2015

 
Under Construction
This is a new page, currently under construction!


Introduction

The SkyGuides feature enable users to create and view interactive sky tours for KStars.

Author: Marcos Cardinot <[email protected]>
Source code: https://github.com/cardinot/kstars/tree/skyguide

SkyGuide Tools

Opening

Both SkyGuide Viewer and SkyGuide Writer can be found on the Tools menu. In addition, they can be opened using the keyboard shortcuts ctrl+k and ctrl+w respectively.

File:Example.jpg

SkyGuide Viewer

The SkyGuide Viewer works like a browser and can be docked to the main KStars window.

File:Example.jpg

SkyGuide Writer

The SkyGuide Writer enables you to create or edit a SkyGuide.

File:Example.jpg

 
Remember
A SkyGuide should have a title, description and one slide at least.


SkyGuide File

A SkyGuide is essentially a zip archive containing a JSON file that must be named as guide.json and the source images (if any).

Warning
The JSON file must be in the root of its zip archive.

JSON File

Fields

Key Type Version Description
Tool KStars'
formatVersion int 1.0.0+ master Format version
header Object 1.0.0+ master Header fields (order does not matter)
slides Array 1.0.0+ master Array of objects containing the information of each slide (order matter).
authors Array 1.0.0+ master Array of objects containing the information of each author (order matter).
creationDate String 1.0.0+ master The date of creation of its SkyGuide in "yyyy-mm-dd" format.
language String 1.0.0+ master The language of its SkyGuide.
centerPoint String 1.0.0+ master [optional] when this slide is open, select this sky object.
image String 1.0.0+ master [optional] path to an image that will be displayed on this slide.
skyDateTime String 1.0.0+ master [optional] when this slide is opened, changes the sky date!
zoomFactor Int 1.0.0+ master [optional] a number between 250 and 5000000.

guides.json (1)

{
   "formatVersion": 1,
   "header": {
       "authors": [
           {
               "email": "String",
               "name": "String",
               "url": "String"
           }
       ],
       "creationDate": "2015-08-20",
       "description": "String",
       "language": "String",
       "title": "String",
       "version": 1
   },
   "slides": [
       {
           "title": "String",
           "text": "String",
           "centerPoint": "Sky Object",
           "image": "kstars.png",
           "skyDateTime": "",
           "zoomFactor": 0
       }
   ]
}

Installing a SkyGuide

 
Remember
The installation directory must be writable!

GUI

  • Open the SkyGuide Viewer tool
  • Click on the 'Install' button on the lower toolbar
  • Select the guide file (zip archive)

Manually

  • Go to the installation directory
  • Extract your SkyGuide (zip archive) on the tools/skyguide/resources/guides directory