<chapter id="dumpmode">
<title>Command-Line mode for Image Generation</title>
<indexterm><primary>Image-dump Mode</primary></indexterm>

<para>
You can use &kstars; to generate an image of the sky 
without actually launching the <acronym>GUI</acronym>
portion of the program.  To use this feature, start
&kstars; from a command prompt using arguments to
specify the filename for the image, as well as the 
desired image dimensions:

<cmdsynopsis>
<command>kstars</command>
<arg choice="plain">--dump</arg>
<arg>--filename <replaceable>kstars.png</replaceable></arg>
<arg>--height <replaceable>640</replaceable></arg>
<arg>--width <replaceable>480</replaceable></arg>
<arg>--script <replaceable>myscript.kstars</replaceable></arg>
<arg>--date <replaceable>"4 July 1976 
12:30:00"</replaceable></arg>
</cmdsynopsis>
</para>
<para>
If no filename is specified, it generates a file 
named <filename>kstars.png</filename>.  It will attempt to 
generate an image that matches the extension of your filename.  
The following extensions are recognized: <quote>png</quote>, 
<quote>jpg</quote>, <quote>jpeg</quote>, <quote>gif</quote>,
<quote>pnm</quote>, and <quote>bmp</quote>.  If the filename
extension is not recognized, it defaults to the 
<acronym>PNG</acronym> image type.
</para>
<para>
Likewise, if the image width and height are not specified, 
they default to 640 and 480, respectively.
</para>
<para>
By default, &kstars; will read in the options values stored in 
your <filename>$KDEHOME/share/config/kstarsrc</filename> file
to determine where the image will be centered, and how it is 
rendered.  This means you need to run &kstars; in normal GUI 
mode, and exit the program when it is set up with the desired 
options for the generated images.  This is not very flexible, 
so we also provide the ability to execute a &kstars; 
<acronym>DCOP</acronym> script to set the scene before 
generating the image.  The filename you specify as the 
script argument should be a valid &kstars;
<acronym>DCOP</acronym> script, such as one created with the
<link linkend="tool-scriptbuilder">Script Builder Tool</link>.
The script can be used to set where the image is pointing, 
set the geographic location, set the time and date, change the
Zoom level, and adjust other view options.  Some of the 
<acronym>DCOP</acronym> functions make no sense in non-GUI 
mode (such as <function>waitForKey()</function>); if these 
functions are encountered while parsing the script, they are
simply ignored.
</para>
<para>
By default, &kstars; will use the system CPU time and date for 
generating the image.  Alternatively, you may specify a time 
and date with the <quote>--date</quote> argument.  You can also 
use this argument for specifying the startup date in normal 
GUI mode.  
</para>

</chapter>