Changes between Version 24 and Version 47 of Help/CommandLineOptions


Ignore:
Timestamp:
(multiple changes)
Author:
(multiple changes)
Comment:
(multiple changes)

Legend:

Unmodified
Added
Removed
Modified

  • Help/CommandLineOptions

    v24 v47  
    11[[TranslatedPages]]
     2[[PageOutline(2)]]
     3
    24= Command Line Options =
    3 {{{#!comment
    4 unfinished hb-
    5 }}}
    6 Starting JOSM is affected by three groups of command line options.
    7 Most important are the ''Programm arguments'' and also the ''Java options''. The ''run-options'' are involved in Web Start only. 
     5
     6Four types of command line options affect JOSM:
     7 * The [#Programarguments Program arguments⤓] directly control JOSM. They are called ''args'' by Java.
     8 * The [#Javaoptions Java options⤓] affect its environment (JVM) and are sometimes named ''VM arguments''.
     9 * The [#run-options Run-options⤓] are involved in WebStart. Some are for diagnosis and import.
     10 * Some [#Otheroptions Other options⤓] for helper programs.
    811
    912{{{
    1013#!sh
    1114# Running a jar
    12 java [Java options] -jar josm-tested.jar [Programm arguments]
    13 
    14 # Web Start
    15 javaws [run-options] josm.jnlp
    16 }}}
    17 
    18 
    19 Java Virtual Machine options::
    20  Control the handler of virtual machine, for example `--Xmx2048m`. The `--jar jarfile` part is a java option, too.
    21  Control the environment inside the virtual machine for JOSM, for example `-Djosm.home=/home/user/.josm_dev`
    22 WebStart run-options::
    23  Control the startup of the handler, for example `-J--Xmx2048m` to hand over the string 'Xmx2048m' to the JVM
    24 `--offline`
    25 
    26 
    27 === Programm arguments ===#Postjararguments
    28 
    29 Also called ''Post jar arguments'' here or ''args'' by Java.
    30 The order of these arguments behind the jarfile in the command line is important for some of them.
    31 
    32 The first argument is the ''commmand'' for JOSM. The three possible commmands are `one` for normal work, `one` for image and `one` for something other. If JOSM can't recognize a command the default is assumed and the usual GUI is started.
    33 
    34 The following arguments can be URLs, coordinates, options with own arguments and filenames. See the output of the --help option below.
    35 
    36 {{{
    37 --help|-h                                 Show this help
    38 --geometry=widthxheight(+|-)x(+|-)y       Standard unix geometry argument
    39 [--download=]minlat,minlon,maxlat,maxlon  Download the bounding box
    40 [--download=]<URL>                        Download the location at the URL (with lat=x&lon=y&zoom=z)
    41 [--download=]<filename>                   Open a file (any file type that can be opened with File/Open)
    42 --downloadgps=minlat,minlon,maxlat,maxlon Download the bounding box as raw GPS
    43 --downloadgps=<URL>                       Download the location at the URL (with lat=x&lon=y&zoom=z) as raw GPS
    44 --selection=<searchstring>                Select with the given search
    45 
    46 --[no-]maximize                           Launch in maximized mode
    47 --reset-preferences                       Reset the preferences to default
    48 --load-preferences=<url-to-xml>           Changes preferences according to the XML file
    49 --set=<key>=<value>                       Set preference key to value
    50 --language=<language>                     Set the language
    51 --version                                 Displays the JOSM version and exits
    52 --debug                                   Print debugging messages to console
    53 --skip-plugins                            Skip loading plugins
    54 --offline=<osm_api|josm_website|all>      Disable access to the given resource(s), separated by comma
    55 }}}
    56 
    57 Make sure you load some data if you use `--selection`.
    58 The --offline list may have commata between its items osm_api,josm_website.
    59 
    60 === Java options ===#JOSMJVMoptions
    61 
    62 These options are sometimes called ''JOSM JV options'' in this help or ''VM arguments'' in the JOSM status report.
    63 
    64 provided as Java system properties
    65 {{{
    66 -Djosm.pref=/PATH/TO/JOSM/PREF            Set the preferences directory
    67 -Djosm.userdata=/PATH/TO/JOSM/USERDATA    Set the user data directory
    68 -Djosm.cache=/PATH/TO/JOSM/CACHE          Set the cache directory
    69 -Djosm.home=/PATH/TO/JOSM/HOMEDIR         Relocate all 3 directories to homedir.
    70 }}}
    71 `-Djosm.home` has lower precedence, i.e. the specific setting overrides this general one.
    72 
    73 For some tasks, JOSM has a large appetite for memory. On the one hand, it may be necessary to configure an  -Xmx memory size that supports more JOSM plugins and other JOSM editing features. On the other hand, slow systems or those systems with few memory resources, can be stabilized by restricting JOSM memory use.  These example Java memory settings provide examples that start with systems that have few memory resources to systems with vast amounts of memory.
    74 {{{
    75 -Xmx...m                                  Set maximum Java heap size in megabytes
    76 -Xmx256m
    77 -Xmx1024m
    78 -Xmx2048m
    79 }}}
    80 
    81 examples
    82 {{{
    83 #!sh
    84 java -jar josm.jar track1.gpx track2.gpx london.osm
    85 java -jar josm.jar https://www.openstreetmap.org/#map=13/43.2/11.1
    86 java -jar josm.jar london.osm --selection=http://www.ostertag.name/osm/OSM_errors_node-duplicate.xml
    87 java -jar josm.jar 43.2,11.1,43.4,11.4
    88 java -jar josm.jar --set=expert=true
    89 java -Djosm.pref=$XDG_CONFIG_HOME -Djosm.userdata=$XDG_DATA_HOME -Djosm.cache=$XDG_CACHE_HOME -jar josm.jar
    90 java -Djosm.home=/home/user/.josm_dev -jar josm.jar
    91 java -Xmx1024m -jar josm.jar
    92 }}}
    93 
    94 Parameters `--download`, `--downloadgps` and `--selection` are processed in this order.
    95 
    96 
    97 The option group names used here follow the documentation on [https://docs.oracle.com/javase/8/docs/technotes/tools/unix/java.html#CBBIJCHG Runtime Engine] and on [https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javaws.html Web Start].
    98 
    99 
    100 === See also ===
    101 * [wiki:Help/Preferences Preferences] - overview page about all "preferences"
    102 * [[jnlpOptions]]
     15java [Java options] -jar josm.jar [Program arguments]
     16
     17# Launch a Web Start
     18javaws [Run-options] -J[Java option] josm.jnlp
     19}}}
     20
     21The [wikitr:/Help/Action/ShowStatusReport Status Report] from the Help menu lists the given Program arguments and Java options.
     22Some [#Examples examples⤓] for both of them are shown below.
     23
     24**Note:** The term {{{josm.jar}}} is a common abbreviation for the file names ''josm-tested.jar'' and ''josm-latest.jar''.
     25The term ''josm.jnlp'' also stands for ''josm-latest.jnlp''.
     26As usual the command line arguments are separated by space from each other.
     27
     28
     29== Program arguments for JOSM ==#Programarguments
     30
     31The first argument can be a **command** for JOSM to make it work autonomous.
     32The commands are `render`, `project` or `runjosm` as default.
     33
     34The remaining arguments are **options** for JOSM.
     35They can be URLs, filenames, coordinates, simple options and option=value pairs.
     36
     37The options for runjosm are listed in the following.
     38At the bottom are the options for the commands [#Programargumentsrendering render⤓] and [#Programargumentsproject project⤓].
     39
     40{{{
     41usage:
     42        java -jar josm.jar [<command>] <options>...
     43
     44commands:
     45        runjosm     launch JOSM (default, performed when no command is specified)
     46        render      render data and save the result to an image file
     47        project     convert coordinates from one coordinate reference system to another
     48        validate    validate data
     49
     50For details on the render and project commands, run them with the --help option.
     51The remainder of this help page documents the runjosm command.
     52
     53options:
     54        --help|-h                                 Show this help
     55        --geometry=widthxheight(+|-)x(+|-)y       Standard unix geometry argument
     56        [--download=]minlat,minlon,maxlat,maxlon  Download the bounding box
     57        [--download=]<URL>                        Download the location at the URL (with lat=x&lon=y&zoom=z)
     58        [--download=]<filename>                   Open a file (any file type that can be opened with File/Open)
     59        --downloadgps=minlat,minlon,maxlat,maxlon Download the bounding box as raw GPS
     60        --downloadgps=<URL>                       Download the location at the URL (with lat=x&lon=y&zoom=z) as raw GPS
     61        --selection=<searchstring>                Select with the given search
     62        --[no-]maximize                           Launch in maximized mode
     63        --reset-preferences                       Reset the preferences to default
     64
     65        --load-preferences=<url-to-xml>           Changes preferences according to the XML file
     66
     67        --set=<key>=<value>                       Set preference key to value
     68
     69        --language=<language>                     Set the language
     70
     71        --version                                 Displays the JOSM version and exits
     72
     73        --status-report                           Show status report with useful information that can be attached to bugs
     74
     75        --debug                                   Print debugging messages to console
     76
     77        --skip-plugins                            Skip loading plugins
     78
     79        --offline=<OSM_API|JOSM_WEBSITE|CACHE_UPDATES|CERTIFICATES|ALL>
     80                                                  Disable access to the given resource(s), separated by comma
     81                                                  <OSM API|JOSM website|Cache updates|Certificates|All>
     82}}}
     83
     84The `--download=` part of the download option is optional.
     85The arguments `--download`, `--downloadgps` and `--selection` are processed in this order.
     86The value `<url-to-xml>` can point to a local file with `file:relative/path/name.xml`.
     87The items in the `--offline` value are separated by comma.
     88
     89
     90== Java options ==#Javaoptions
     91
     92They control the Java virtual machine [https://docs.oracle.com/javase/8/docs/technotes/tools/unix/java.html (JVM)] and can set [https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html properties] inside it. JOSM reads some of them directly, for example `josm.home`. Others like `user.language` and `user.country` affect the default settings of the JVM which affect JOSM too.
     93
     94{{{
     95Java system properties options:
     96    -Djosm.dir.name=JOSM                      Change the JOSM directory name
     97    -Djosm.pref=/PATH/TO/JOSM/PREF            Set the preferences directory
     98                                              Default (Linux XDG): /home/name/.config/JOSM
     99                                              Default (Windows): C:\Users\name\AppData\Roaming\JOSM
     100    -Djosm.userdata=/PATH/TO/JOSM/USERDATA    Set the user data directory
     101                                              Default (Linux XDG): /home/name/.local/share/JOSM
     102                                              Default (Windows): C:\Users\name\AppData\Roaming\JOSM
     103    -Djosm.cache=/PATH/TO/JOSM/CACHE          Set the cache directory
     104                                              Default (Linux XDG): /home/name/.cache/JOSM
     105                                              Default (Windows): C:\Users\name\AppData\Local\JOSM\cache
     106    -Djosm.home=/PATH/TO/JOSM/HOMEDIR         Set the common directory for preferences,
     107                                              user data and ./cache/. Lower precedence.
     108                                              Will get overridden from specific setting.
     109    -Xmx...m                                  Set maximum Java heap size in megabytes.
     110                                              May avoid Out-of-Memory errors.
     111}}}
     112
     113The `-Xmx...m` option may be useful when [wikitr:/Download#Outofmemory Out of Memory] errors arise.
     114If you set a common directory with `Djosm.home` then JOSM will create the subdirectories ./autosave, ./cache and ./validator.
     115If a value has spaces, then enclose it in quotation marks like `"josm dev"`.
     116
     117When the non-ASCII characters in the command prompt are scrambled, use `-Dfile.encoding=Cp850` to receive text from Java in another [https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html code page].
     118Which [https://msdn.microsoft.com/de-de/library/windows/desktop/dd317756%28v=vs.85%29.aspx code page] is used shows `chcp⏎` in the terminal.
     119For UTF-8 on Windows, invoke `chcp 65001` in the Windows terminal window before launching JOSM using `java -Dfile.encoding=UTF-8 -jar josm.jar`
     120
     121JOSMs Debian package `josm-latest` uses `-Djosm.dir.name=JOSM-latest` to offer parallel installations in the XDG base directories.
     122
     123[=#Examples **Examples for JOSM runjosm options and Java options**]
     124{{{
     125#!sh
     126# Load three files
     127  java -jar josm.jar track1.gpx BigBen.jpg "london data.osm"
     128# Download from OSM according to an URL with zoom and coordinates
     129  java -jar josm.jar https://www.openstreetmap.org/#map=18/51.501/-0.124
     130# Download a bounding box and select every element matching a string
     131  java -jar josm.jar 51.500,-0.126,51.502,-0.122 --selection="Big Ben"
     132#
     133# Set directory for JOSM according to a property from the operating system
     134  java -Djosm.pref=$XDG_CONFIG_HOME -jar josm.jar
     135# Quotations for a value with space and show JOSMs GUI in English
     136  java -Djosm.dir.name="josm dev" -jar josm.jar --language=en
     137# Set the common directory in a sub-subdirectory below the active command prompt
     138  java -Djosm.home=biketour2017/london -jar josm.jar
     139# More memory and without phoning home
     140  java -Xmx1024m --set=message.notifier.enabled=false  -jar josm.jar
     141#
     142# Start in an English environment and log debug info plus messages from stderr
     143  java -Duser.language=en -jar josm.jar --debug 1>logfile.txt 2>&1
     144}}}
     145
     146
     147== Run-options for Java Web Start ==#run-options
     148
     149The run-options are read by the `javaws` command. They control the Web Start mechanism, can encapsulate Java options and can diagnose Java.
     150{{{
     151#!sh
     152# Control
     153  -offline                  Allows to Web Start JOSM without internet access
     154
     155# Encapsulate
     156  -J<java option>           Supplies the <java option> to the JVM
     157  -J-Xmx1024m               Here: Set maximum Java heap size to 1024 megabyte
     158
     159# Diagnosis
     160javaws -viewer            Shows the Cache Viewer in the Java Control Panel
     161# Allows to opens the Java Control Panel from the command line.
     162
     163javaws -clearcache        Removes all non-installed applications from the cache
     164# Equal to 'Delete Files and Applications' from the 'Temporary File Settings' invoked
     165# by the 'Settings' button in the 'General' tab of the Java Control Panel.
     166# javaws -Xclearcache on OpenJDK
     167}}}
     168
     169The `-J` run-option takes its part behind the J letter and supplies that as Java option.
     170The [wikitr:/Help/jnlpOptions jnlp-File] used by [https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javaws.html Web Start] offers a second way to [https://docs.oracle.com/javase/8/docs/technotes/guides/javaws/developersguide/syntax.html  set options] for JRE and for the JOSM program directly.
     171
     172The `javaws` command has some control options on all systems.
     173
     174The `-clearcache` option and clearing the cache via the Java Control Panel will both delete JNLP based icons from the Desktop. The JOSM icon will be gone if it was placed as result of a click in a web browser on a jnlp-file.
     175
     176== Other options ==#Otheroptions
     177
     178The Launcher `josm.exe` aka [http://launch4j.sourceforge.net/docs.html#Runtime_options Launch4j] (only on [wikitr:/Download#Mswindowswrapper MS Windows]) may give some debug info.
     179{{{
     180#!sh
     181josm.exe --j4l-debug      Tries to write a launch4j.log to current directory
     182josm.exe --j4l-dont-wait  Ends the wrapper after invoking JOSM.
     183}}}
     184
     185== Command line for Render and Project ==
     186
     187=== JOSM rendering Program arguments ===#Programargumentsrendering
     188
     189{{{
     190Usage:
     191        java -jar josm.jar render <options>
     192
     193Description:
     194Renders data and saves the result to an image file.
     195
     196Options:
     197        --help|-h                 Show this help
     198        --input|-i <file>         Input data file name (.osm)
     199        --output|-o <file>        Output image file name (.png); defaults to 'out.png'
     200        --style|-s <file>         Style file to use for rendering (.mapcss or .zip)
     201                                  This option can be repeated to load multiple styles.
     202        --setting <key>:<value>   Style setting (in JOSM accessible in the style list dialogue right click menu)
     203                                  Applies to the last style loaded with the --style option.
     204        --zoom|-z <lvl>           Select zoom level to render. (integer value, 0=entire earth, 18=street level)
     205        --scale <scale>           Select the map scale
     206                                  A value of 10000 denotes a scale of 1:10000 (1 cm on the map equals 100 m on the ground; display resolution: 96 dpi)
     207                                  Options --zoom and --scale are mutually exclusive.
     208        --bounds|-b auto|<min_lon>,<min_lat>,<max_lon>,<max_lat>
     209                                  Area to render, default value is 'auto'
     210                                  With keyword 'auto', the downloaded area in the .osm input file will be used (if recorded).
     211        --anchor <lon>,<lat>      Specify bottom left corner of the rendering area
     212                                  Used in combination with width and height options to determine the area to render.
     213        --width-m <number>        Width of the rendered area, in meter
     214        --height-m <number>       Height of the rendered area, in metres
     215        --width-px <number>       Width of the target image, in pixels
     216        --height-px <number>      Height of the target image, in pixels
     217        --projection <code>       Projection to use, default value 'epsg:3857' (web-Mercator)
     218        --max-image-size <number> Maximum image width/height in pixel ('0' means no limit), default value: 20000
     219
     220To specify the rendered area and scale, the options can be combined in various ways:
     221  * --bounds (--zoom|--scale|--width-px|--height-px)
     222  * --anchor (--width-m|--width-px) (--height-m|--height-px) (--zoom|--scale)
     223  * --anchor --width-m --height-m (--width-px|--height-px)
     224  * --anchor --width-px --height-px (--width-m|--height-m)
     225If neither 'bounds' nor 'anchor' is given, the default value --bounds=auto takes effect and the bounds of the download area in the .osm input file are used.
     226
     227Examples:
     228  java -jar josm.jar render -i data.osm -s style.mapcss -z 16
     229  josm render -i data.osm -s style.mapcss --scale 5000
     230  josm render -i data.osm -s style.mapcss -z 16 -o image.png
     231  josm render -i data.osm -s elemstyles.mapcss --setting hide_icons:false -z 16
     232  josm render -i data.osm -s style.mapcss -s another_style.mapcss -z 16 -o image.png
     233  josm render -i data.osm -s style.mapcss --bounds 21.151,51.401,21.152,51.402 -z 16
     234  josm render -i data.osm -s style.mapcss --anchor 21.151,51.401 --width-m 500 --height-m 300 -z 16
     235  josm render -i data.osm -s style.mapcss --anchor 21.151,51.401 --width-m 500 --height-m 300 --width-px 1800
     236  josm render -i data.osm -s style.mapcss --scale 5000 --projection epsg:4326
     237}}}
     238
     239=== JOSM projection Program arguments ===#Programargumentsprojection
     240
     241{{{
     242Usage:
     243        java -jar josm.jar project <options> <crs> +to <crs> [file]
     244
     245Description:
     246Converts coordinates from one coordinate reference system to another.
     247
     248Options:
     249        --help|-h         Show this help
     250        -I                Switch input and output crs
     251        -r                Switch order of input coordinates (east/north, lon/lat)
     252        -s                Switch order of output coordinates (east/north, lon/lat)
     253
     254<crs>:
     255The format for input and output coordinate reference system is similar to that of the PROJ.4 software.
     256
     257[file]:
     258Reads input data from one or more files listed as positional arguments. When no files are given, or the filename is "-", data is read from standard input.
     259
     260Examples:
     261    java -jar josm.jar project +init=epsg:4326 +to +init=epsg:3857 <<<"11.232274 50.5685716"
     262       => 1250371.1334500168 6545331.055189664
     263
     264    java -jar josm.jar project +proj=lonlat +datum=WGS84 +to +proj=merc +a=6378137 +b=6378137 +nadgrids=@null <<EOF
     265    11d13'56.19"E 50d34'6.86"N
     266    118d39'30.42"W 37d20'18.76"N
     267    EOF
     268       => 1250371.1334500168 6545331.055189664
     269          -1.3208998232319113E7 4486401.160664663
     270}}}
     271
     272
     273== See also ==
     274* [wikitr:/Download#Troubleshooting Troubleshooting Java]
     275* [wikitr:/InstallNotes Installation notes]
     276* [wikitr:/Help/Preferences Preferences] - Preferences overview
     277
     278----
     279Back to [wikitr:/Help Main Help]