.. _properties-file:

The configuration file
**********************

There is a configuration file which stores most of the configration settings
of Gaia Sky. This section is devoted
to these seetings that are not represented in the GUI but are still
configurable. The configuration file is located in
``$GS_CONFIG/global.properties`` (see :ref:`folders <folders>`). The file is annotated with
comments specifying the function of most properties. However, here is an 
explanation of some of the properties
found in this file that are not represented in the GUI.


-  **scene.octree.maxstars** -- the maximum number of stars loaded at a time
   from LOD (octree-backed) catalogs. Increase this to allow for more stars 
   to be loaded. When this number is hit, the application unloads old, unobserved
   octants.
-  **controls.blacklist** -- list of game controllers to ignore.
-  **data.limit.mag** -- this contains the limiting magnitude above which
   stars shall not be loaded. Not all data loaders implement this. It is
   now deprecated.

Below is the default ``global.properties`` file for Gaia Sky 3.0.0.

.. code:: jproperties

    # GAIA SKY CONFIGURATION FILE

    # Configuration version
    properties.version=30000

    # Multithreading enabled?
    global.conf.multithreading=true

    # In case multithreading is on, this sets the number of threads to create.
    # If zero or negative, it uses the default value, which is the number of cores.
    # You should not set this much higher than the actual number of physical cores in your computer.
    global.conf.numthreads=0

    # SCREEN CONFIGURATION

    # This activates output to the default monitor. Deactivate only to enable headless mode.
    graphics.screen.screenoutput=true

    # Fullscreen mode width
    graphics.screen.fullscreen.width=1920

    # Fullscreen mode height
    graphics.screen.fullscreen.height=1080

    # Windowed mode width
    graphics.screen.width=

    # Windowed mode height
    graphics.screen.height=

    # Is fullscreen activated?
    graphics.screen.fullscreen=false

    # Resizable enabled in windowed mode
    graphics.screen.resizable=true

    # Enable or disable vsync to prevent screen tearing. FPS will be limited to monitor refresh frequency.
    graphics.screen.vsync=true

    # Limiting FPS - caps the frame rate to the given value. Set to zero to uncap
    graphics.limit.fps=0


    # IMAGE RENDERING SYSTEM CONFIGURATION
    # The frame output mode: [simple|redraw]
    # simple - the current openGL buffer is written to a file. Screenshot will look exactly like the screen
    # redraw - the image is redrawn with optionally different effects and resolution, and then it is written to a file.
    graphics.render.mode=simple

    graphics.render.width=1280

    graphics.render.height=720

    # Target FPS for the rendered images
    graphics.render.targetfps=60

    # Target FPS for the camera recording
    graphics.camera.recording.targetfps=60

    # Path type of camera position in keyframe mode: SPLINE | LINEAR
    graphics.camera.keyframe.path.position=SPLINE
    # Path type of camera orientation in keyframe mode: SPLINE | LINEAR
    graphics.camera.keyframe.path.orientation=SPLINE

    # Automcatically activate frame output system when camera file is playing
    graphics.camera.recording.frameoutputauto=false

    # Path and image name
    graphics.render.folder=

    graphics.render.filename=gaiasky

    # Write time in frame output mode and in screenshots
    graphics.render.time=false

    # Format, wither png or jpg
    graphics.render.format=jpg

    # Quality, only relevant if format is jpg, in [0..1]
    graphics.render.quality=0.93

    # Lazy initialization of textures
    scene.lazy.texture=true
    # Lazy initalization of meshes
    scene.lazy.mesh=true

    # SCREENSHOT
    # The screenshot mode: [simple|redraw]
    # simple - the current openGL buffer is written to a file. Screenshot will look exactly like the screen
    # redraw - the image is redrawn with optionally different effects and resolution, and then it is written to a file.
    screenshot.mode=simple

    screenshot.folder=

    screenshot.width=1920

    screenshot.height=1080

    # Format, wither png or jpg
    screenshot.format=jpg

    # Quality, only relevant if format is jpg, in [0..1]
    screenshot.quality=0.93


    # DATA

    # Location of the data folder.
    # Windows and macOS: in your user directory: $HOME/.gaiasky/data
    # Linux: ~/.local/share/gaiasky/data
    data.location=

    # Selected catalogs to load at startup, separated by ':' (linux, macOS), or ';' (windows)
    data.json.catalog=

    # Comma-separated list of files within the data folder with the non-particle objects to load (planets, constellations, etc)
    # Additionally to the files defined here, any file in the data folder with the format "autoload-*.json" will also be
    # load using the JsonLoader
    data.json.objects=data/data-main.json

    # Use all terms in position algorithms (VSOP87 and moon coordinates). Taxes the CPU
    data.highaccuracy.positions=false

    data.limit.mag=20.0

    # Location of the skybox within the data folder (data/tex/skybox/[...]/)
    data.skybox.location=data/tex/skybox/gaiasky/


    # SCENE PROPERTIES

    # Name of the startup object
    scene.object.startup=Earth

    # Graphics quality setting: low, normal, high, ultra
    scene.graphics.quality=normal

    # Camera speed limit
    # 0 - 100 km/h
    # 1 - 0.5c
    # 2 - 0.8c
    # 3 - 0.9c
    # 4 - 0.99c
    # 5 - 0.99999c
    # 6 - c (3e8 m/s)
    # 7 - 2*c
    # 8 - 10*c
    # 9 - 1000*c
    # 10 - 1 AU/s
    # 11 - 10 AU/s
    # 12 - 1000 AU/s
    # 13 - 10000 AU/s
    # 14 - 1 pc/s
    # 15 - 2 pc/s
    # 16 - 10 pc/s
    # 17 - 1000 pc/s
    # 18 - No limit
    scene.camera.speedlimit=18

    # Camera velocity multiplier when in focus mode
    scene.camera.focus.vel=2.5

    # Camera turn velocity
    scene.camera.turn.vel=2062.0

    # Camera rotation
    scene.camera.rotate.vel=3776.0

    # Initial field of view of the camera, in degrees
    scene.camera.fov=45.0

    # Whether cinematic camera is active
    scene.camera.cinematic=false

    # Target on in free mode. This scales the velocity of the camera according to the distance to the closest object
    scene.camera.free.targetmode=true

    # Object fade time in ms
    scene.object.fadems=2500

    # Star brightness factor
    scene.star.brightness=2.3

    # Modulate the brightness of stars with this power
    scene.star.brightness.pow=0.75

    # Size scaling of stars
    scene.star.point.size=9.5

    # Texture index, see $GS_DATA/tex/base/star-tex-xx-low.png
    # 1 - horizontal spike
    # 2 - god rays
    # 3 - horizontal and vertical spikes
    # 4 - simple radial profile
    scene.star.tex.index=4

    # Number of nearest stars to process in star groups
    # This determines the maximum number of billboards, labels, velocity arrows, etc.
    scene.star.group.nearest=500

    # Flag to enable or disable the star billboards when stars are close
    scene.star.group.billboard.flag=true

    # Ambient light level, between 0 and 1.
    scene.ambient=0.0

    # Lock focus to object
    scene.focuslock=true

    # Lock also the orientation of the focus to the camera
    scene.focuslock.orientation=false

    # Label size factor. Controls label size
    scene.label.size=1.2

    # Label number factor. Controls how many stars have labels
    scene.label.number=1.3

    # Line width factor to multiply line width with
    scene.line.width=1.0

    # Threshold radius/distance for stars. This controls the threshold to render stars as points or as quads
    # radius/distance limit for rendering as quad. If angle is any bigger, we render as a model.
    scene.star.threshold.quad=0.0
    # radius/distance limit for rendering as point. If angle is any bigger, we render as quad.
    scene.star.threshold.point=1.7E-8
    # radius/distance limit for rendering at all. If angle is smaller than this quantity, no rendering happens.
    scene.star.threshold.none=0.0

    # radius/distance above which we start painting stars in octant with fade in. Angle in radians.
    scene.octant.threshold.0=1.477
    # radius/distance below which we paint stars in octant with fade out. Above this angle, inner stars are painted with full brightness. Angle in radians.
    scene.octant.threshold.1=1.877

    # In the case of multifile LOD datasets (such as DR2+), this setting contains 
    # the maximum number of stars loaded at a time. If the number of loaded stars 
    # exceeds this setting, the system will start looking for the best candidates
    # to be unloaded and start unloading data. Should not be set too low, and this should
    # be balanced with the dataset and the draw distance.
    # 6.0 M is calibrated to use 4Gb heap space with the default dataset
    scene.octree.maxstars=6000000

    # The minimum alpha (opacity) of stars
    scene.point.alpha.min=0.1
    # The maximum alpha (opacity) of stars
    scene.point.alpha.max=1.0

    # Line renderer type: 0 - performance (GL LINES), 1 - polyline quadstrips (quality)
    scene.renderer.line=1

    # Orbit renderer
    # 0 - use the line renderer setting (see below) - slower, looks better
    # 1 - use GPU VBOs - faster, looks worse
    scene.renderer.orbit=0


    # If on, particles fade in and out between levels of detail
    scene.octree.particle.fade=true

    # Length factor of proper motion vectors [1 - 50]
    scene.propermotion.lenfactor=8.35
    # Scale factor of proper motion vectors [1 - 30]
    scene.propermotion.numfactor=5.35
    # Color mode for velocity vectors
    # 0 - direction
    # 1 - length (speed)
    # 2 - has radial velocity
    # 3 - redshift
    # 4 - single color
    scene.propermotion.colormode=0
    # Whether to show arrowheads or not
    scene.propermotion.arrowheads=true
    # Maximum number of proper motion vectors per star group. Overrides default quality-dependent
    # setting. Negative to use default
    scene.propermotion.maxnumber=-1

    # Shadows enabled or disabled
    scene.shadowmapping=true
    # Resolution of the shadow map
    scene.shadowmapping.resolution=1024
    # Number of shadows
    scene.shadowmapping.nshadows=3

    # Elevation type [tessellation|parallax_mapping|none]
    scene.elevation.type=tessellation
    # Elevation multiplier, in [0.0, 10.0]
    scene.elevation.multiplier=2.5

    # Tessellation quality, in [1.0, 7.0]
    scene.tessellation.quality=4.0

    # Show crosshair on focus object
    scene.crosshair.focus=true
    # Show crosshair on closest object
    scene.crosshair.closest=true
    # Show crosshair on home object
    scene.crosshair.home=false

    # Visibility of components
    scene.visibility.Atmospheres=true
    scene.visibility.Planets=true
    scene.visibility.Labels=true
    scene.visibility.Boundaries=false
    scene.visibility.Moons=true
    scene.visibility.Equatorial=false
    scene.visibility.Orbits=true
    scene.visibility.Constellations=false
    scene.visibility.Galactic=false
    scene.visibility.Ecliptic=false
    scene.visibility.RecursiveGrid=false
    scene.visibility.Satellites=true
    scene.visibility.Stars=true
    scene.visibility.MilkyWay=true
    scene.visibility.Asteroids=false
    scene.visibility.Clusters=false
    scene.visibility.Locations=false
    scene.visibility.Countries=false
    scene.visibility.Galaxies=true
    scene.visibility.Nebulae=true
    scene.visibility.Meshes=false
    scene.visibility.Titles=false
    scene.visibility.Effects=false
    scene.visibility.Clouds=true
    scene.visibility.Ruler=true
    scene.visibility.VelocityVectors=false
    scene.visibility.Axes=true
    scene.visibility.Others=true


    # POSTPROCESSING

    # Antialiasing mode. None, NFAA or FXAA. 
    # 0  - No antialiasing
    # -1 - FXAA
    # -2 - NFAA
    postprocess.antialiasing=-1

    # Intensity of the bloom effect, between 0 and 10
    postprocess.bloom.intensity=0.1

    # Activate/deactivate motion blur, 0 or 1
    postprocess.motionblur=0.0

    # Activate/deactivate lens flare, true|false
    postprocess.lensflare=true

    # Activate/deactivate light glow, true|false
    postprocess.lightscattering=true

    # Activate/deactivate fisheye transformation, true|false
    postprocess.fisheye=false

    # Brightness level in [-1..1], defaults to 0
    postprocess.brightness=0.0
    # Contrast level in [0..2], defaults to 1
    postprocess.contrast=1.0
    # Hue level in [0..2], defaults to 1
    postprocess.hue=1.0
    # Saturation level in [0..2], defaults to 1
    postprocess.saturation=1.0
    # Gamma correction value in [0..3], defaults to 1
    postprocess.gamma=1.0
    # Tone mapping type, string in [auto|exposure|aces|uncharted|filmic|none]
    postprocess.tonemapping.type=none
    # Exposure tone mapping in [0..n]. Set 0 to disable
    postprocess.exposure=0.0

    # PROGRAM OPTIONS

    # Show debug info, true|false
    program.debuginfo=false

    # Whether to display the hud or not, true|false
    program.display.hud=false

    # Display coordiantes of pointer (RA/DEC or Lat/Lon), true|false
    program.pointer.coords.display=true

    # Pointer guides
    program.pointer.guides.display=false
    # Pointer guides color (RGBA array)
    program.pointer.guides.color=[1.0, 1.0, 1.0, 0.3]
    # Pointer guides width in pixels
    program.pointer.guides.width=1.5

    # Recursive grid origin: focus | refsys
    program.recursivegrid.origin=refsys
    # Projection lines to recursive grid origin
    program.recursivegrid.origin.lines=true

    # Display minimap
    program.display.minimap=false
    # Minimap size in [150, 350]
    program.minimap.size=200

    # Whether to start in stereoscopic mode or not, true|false
    program.stereoscopic=false

    # Whehter to enable cubemap mode [true|false]
    # Used for panaroama and planetarium mode. See key 'program.cubemap.projection'
    program.cubemap=false

    # Projection to use for the cubemap mode [equirectangular|cylindrical|hammer|fisheye]
    # Set to 'fisheye' for planetarium mode
    program.cubemap.projection=equirectangular

    # Resolution of each face of the cubemap (square frame buffer with a fov=90 in each direction X+ X- Y+ Y- Z+ Z-)
    program.cubemap.face.resolution=1500

    # The aperture angle [deg] of planetarium mode
    program.planetarium.aperture=180.0

    # The focus angle [deg] of planetarium mode from the zenith
    program.planetarium.angle=50.0

    # In a client-server configuration, this makes this instance act as a master
    # which sends input events over the network
    # Incompatible with program.net.slave
    program.net.master=false

    # The following properties define the slaves
    # Each slave listens to a port defined in its program.restport property
    #program.net.master.slaves.0=http://localhost\:13900/api/
    #program.net.master.slaves.1=http://localhost\:13901/api/

    # In a client-server configuration, this makes this instance act as a slave
    # which receives input events over the network
    # Incompatible with program.net.master
    program.net.slave=false

    # Location of the .mpcdi configuration file for this instance
    # Only needed if program.net.slave is true
    program.net.slave.config=

    # If you don't have an mpcdi file, use these next properties to
    # configure the orientation. In order for this to work, you also
    # need to set fullscreen=true, the right fullscreen resolution
    # and the right field of view angle.

    # Yaw angle (turn head right)
    program.net.slave.yaw=
    # Pitch angle (turn head up)
    program.net.slave.pitch=
    # Roll angle (rotate head cw)
    program.net.slave.roll=
    # Warp pfm file
    program.net.slave.warp=
    # Blend png file
    program.net.slave.blend=

    # The stereoscopic profile.
    # 0 - VR headsets
    # 1 - 3DTV (left-right)
    # 2 - 3DTV (top-bottom)
    # 3 - Cross-eye
    # 4 - Parallel view
    # 5 - Anaglyph red-cyan
    program.stereoscopic.profile=2

    # The default location of scripts
    program.scriptlocation=

    # The GUI theme - dark-green | dark-green-x2 | dark-blue | dark-blue-x2 | dark-orange | dark-orange-x2 | night-red | night-red-x2
    program.ui.theme=dark-green

    # Ask for exit confirmation
    program.exit.confirmation=true

    # Enable REST API on this TCP port (negative: disabled)
    program.restport=-1

    # Set to 'default' to use the system default locale, set to language tag (see java.util.Locale#forLanguageTag(), java 7+) to change the locale (en_GB, en_US, es_ES, de_DE, fr, etc.)
    # Leave empty to use default locale
    program.locale=

    # Last time checked for new version
    program.lastchecked=

    # Last version checked
    program.lastversion=

    # URL to check the version - GitHub API call that returns a JSON list
    program.url.versioncheck=https\://gitlab.com/api/v4/projects/langurmonkey%2Fgaiasky/repository/tags

    # Data mirror
    program.url.data.mirror=https\://gaia.ari.uni-heidelberg.de/gaiasky/files/autodownload/
    # URL of data descriptor file
    program.url.data.descriptor=https\://gaia.ari.uni-heidelberg.de/gaiasky/files/autodownload/gaiasky-data-030000.json

    # CONTROLS OPTIONS

    # Controller mappings file
    controls.gamepad.mappings.file=mappings/SDL_Controller.controller

    # Invert look x axis
    controls.invert.x=false
    # Invert look y axis
    controls.invert.y=true

    # Controller debug mode; prints key codes and values
    # DEPRECATED, use --debug flag instead!
    #controls.debugmode=false

    # Blacklist of controller names. All controllers here will not be
    # processed by Gaia Sky. Find the connected controller names in the Preferences
    # window, Controls tab.
    # Double quote controller names and separate them with whitespace characters.
    # Example: controls.blacklist="Microsoft Xbox 360 pad" "Playstation 4 dualshock"
    controls.blacklist=

    # SPACECRAFT OPTIONS

    # Responsiveness, from 0 to 1
    spacecraft.responsiveness=0.4

    # Velocity vector always aligned with spacecraft direction vector
    spacecraft.velocity.direction=false

    # Handling friction in 0..1
    spacecraft.handling.friction=0.37

    # Whether to show the direction and up axes of the spacecraft
    spacecraft.show.axes=false


    # DATA SOURCE OPTIONS

    # Real attitude or NSL attitude?
    data.attitude.real=false