doc/kstars/dumpmode.docbook

   1 <chapter id="dumpmode">
   2 <title>Command-Line mode for Image Generation</title>
   3 <indexterm><primary>Image-dump Mode</primary></indexterm>
   4
   5 <para>
   6 You can use &kstars; to generate an image of the sky
   7 without actually launching the <acronym>GUI</acronym>
   8 portion of the program.  To use this feature, start
   9 &kstars; from a command prompt using arguments to
  10 specify the filename for the image, as well as the
  11 desired image dimensions:
  12
  13 <cmdsynopsis>
  14 <command>kstars</command>
  15 <arg choice="plain">--dump</arg>
  16 <arg>--filename <replaceable>kstars.png</replaceable></arg>
  17 <arg>--height <replaceable>640</replaceable></arg>
  18 <arg>--width <replaceable>480</replaceable></arg>
  19 <arg>--script <replaceable>myscript.kstars</replaceable></arg>
  20 <arg>--date <replaceable>"4 July 1976
  21 12:30:00"</replaceable></arg>
  22 </cmdsynopsis>
  23 </para>
  24 <para>
  25 If no filename is specified, it generates a file
  26 named <filename>kstars.png</filename>.  It will attempt to
  27 generate an image that matches the extension of your filename.
  28 The following extensions are recognized: <quote>png</quote>,
  29 <quote>jpg</quote>, <quote>jpeg</quote>, <quote>gif</quote>,
  30 <quote>pnm</quote>, and <quote>bmp</quote>.  If the filename
  31 extension is not recognized, it defaults to the
  32 <acronym>PNG</acronym> image type.
  33 </para>
  34 <para>
  35 Likewise, if the image width and height are not specified,
  36 they default to 640 and 480, respectively.
  37 </para>
  38 <para>
  39 By default, &kstars; will read in the options values stored in
  40 your <filename>$KDEHOME/share/config/kstarsrc</filename> file
  41 to determine where the image will be centered, and how it is
  42 rendered.  This means you need to run &kstars; in normal GUI
  43 mode, and exit the program when it is set up with the desired
  44 options for the generated images.  This is not very flexible,
  45 so we also provide the ability to execute a &kstars;
  46 <acronym>DCOP</acronym> script to set the scene before
  47 generating the image.  The filename you specify as the
  48 script argument should be a valid &kstars;
  49 <acronym>DCOP</acronym> script, such as one created with the
  50 <link linkend="tool-scriptbuilder">Script Builder Tool</link>.
  51 The script can be used to set where the image is pointing,
  52 set the geographic location, set the time and date, change the
  53 Zoom level, and adjust other view options.  Some of the
  54 <acronym>DCOP</acronym> functions make no sense in non-GUI
  55 mode (such as <function>waitForKey()</function>); if these
  56 functions are encountered while parsing the script, they are
  57 simply ignored.
  58 </para>
  59 <para>
  60 By default, &kstars; will use the system CPU time and date for
  61 generating the image.  Alternatively, you may specify a time
  62 and date with the <quote>--date</quote> argument.  You can also
  63 use this argument for specifying the startup date in normal
  64 GUI mode.
  65 </para>
  66
  67 </chapter>