Changes between Version 12 and Version 47 of Help/CommandLineOptions


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

Legend:

Unmodified
Added
Removed
Modified

  • Help/CommandLineOptions

    v12 v47  
    11[[TranslatedPages]]
    2 
     2[[PageOutline(2)]]
     3
     4= Command Line Options =
     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.
     11
     12{{{
     13#!sh
     14# Running a jar
     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{{{
    341usage:
    4 {{{
    5 #!sh
    6 java <Java-options> -jar josm.jar <options> [file]
    7 }}}
     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
    853options:
    9 {{{
    10 --help|-h                                 Show this help
    11 --geometry=widthxheight(+|-)x(+|-)y       Standard unix geometry argument
    12 [--download=]minlat,minlon,maxlat,maxlon  Download the bounding box
    13 [--download=]<URL>                        Download the location at the URL (with lat=x&lon=y&zoom=z)
    14 [--download=]<filename>                   Open a file (any file type that can be opened with File/Open)
    15 --downloadgps=minlat,minlon,maxlat,maxlon Download the bounding box as raw GPS
    16 --downloadgps=<URL>                       Download the location at the URL (with lat=x&lon=y&zoom=z) as raw GPS
    17 --selection=<searchstring>                Select with the given search
    18 
    19 --[no-]maximize                           Launch in maximized mode
    20 --reset-preferences                       Reset the preferences to default
    21 --load-preferences=<url-to-xml>           Changes preferences according to the XML file
    22 --set=<key>=<value>                       Set preference key to value
    23 --language=<language>                     Set the language
    24 --version                                 Displays the JOSM version and exits
    25 --debug                                   Print debugging messages to console
    26 --offline=<osm_api|josm_website|all>      Disable access to the given resource(s), separated by comma
    27 }}}
    28 options provided as Java system properties
    29 {{{
    30 -Djosm.home=/path/to/JOSM/folder/         Change the folder for all user settings
    31 }}}
    32 For some tasks, JOSM needs a lot of memory. It can be necessary to add the following Java option to specify the maximum size of allocated memory in megabytes. On the other hand, on slow systems or those with less memory, you can make JOSM more stable by restricting its memory use:
    33 {{{
    34 -Xmx...m                                  Set maximum Java heap size in megabytes
    35 }}}
    36 
    37 examples
    38 {{{
    39 #!sh
    40 java -jar josm.jar track1.gpx track2.gpx london.osm
    41 java -jar josm.jar https://www.openstreetmap.org/index.html?lat=43.2&lon=11.1&zoom=13
    42 java -jar josm.jar london.osm --selection=http://www.ostertag.name/osm/OSM_errors_node-duplicate.xml
    43 java -jar josm.jar 43.2,11.1,43.4,11.4
    44 java -Djosm.home=/home/user/.josm_dev -jar josm.jar
    45 java -Xmx400m -jar josm.jar
    46 java -jar josm.jar --set=expert=true
    47 }}}
    48 
    49 Parameters `--download`, `--downloadgps` and `--selection` are processed in this order.
    50 Make sure you load some data if you use `--selection`.
    51 
     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]