wiki:Help/CommandLineOptions

Context Navigation

Version 44 (modified by Hb---, 4 years ago) ( diff )
Debian package uses josm.dir.name option in usr/bin/josm-latest to provide a parallel install

Languages:

Program arguments for JOSM
Java options
Run-options for Java Web Start
Other options
Command line for Render and Project
See also

Command Line Options

Four types of command line options affect JOSM:

The Program arguments⤓ directly control JOSM. They are called args by Java.
The Java options⤓ affect its environment (JVM) and are sometimes named VM arguments.
The Run-options⤓ are involved in WebStart. Some are for diagnosis and import.
Some Other options⤓ for helper programs.

# Running a jar
java [Java options] -jar josm.jar [Program arguments]

# Launch a Web Start
javaws [Run-options] -J[Java option] josm.jnlp

The Status Report from the Help menu lists the given Program arguments and Java options. Some examples⤓ for both of them are shown below.

Note: The term josm.jar is a common abbreviation for the file names josm-tested.jar and josm-latest.jar. The term josm.jnlp also stands for josm-latest.jnlp. As usual the command line arguments are separated by space from each other.

Program arguments for JOSM

The first argument can be a command for JOSM to make it work autonomous. The commands are render, project or runjosm as default.

The remaining arguments are options for JOSM. They can be URLs, filenames, coordinates, simple options and option=value pairs.

The options for runjosm are listed in the following. At the bottom are the options for the commands render⤓ and project⤓.

usage:
	java -jar josm.jar [<command>] <options>...

commands:
	runjosm     launch JOSM (default, performed when no command is specified)
	render      render data and save the result to an image file
	project     convert coordinates from one coordinate reference system to another

For details on the render and project commands, run them with the --help option.
The remainder of this help page documents the runjosm command.

options:
	--help|-h                                 Show this help
	--geometry=widthxheight(+|-)x(+|-)y       Standard unix geometry argument
	[--download=]minlat,minlon,maxlat,maxlon  Download the bounding box
	[--download=]<URL>                        Download the location at the OSM-style URL
 	[--download=]<filename>                   Open a file (any type suitable for File/Open)
	--downloadgps=minlat,minlon,maxlat,maxlon Download the bounding box as raw GPS
	--downloadgps=<URL>                       Download the location at the URL as raw GPS
	--selection=<searchstring>                Select with the given search
	--[no-]maximize                           Launch in maximised mode
	--reset-preferences                       Reset the preferences to default

	--load-preferences=<url-to-xml>           Changes preferences according to the XML file

	--set=<key>=<value>                       Set preference key to value

	--language=<language>                     Set the language

	--version                                 Displays the JOSM version and exits

	--debug                                   Print debug info on Mapview and stdout (console)

	--skip-plugins                            Skip loading plugins

	--offline=<OSM_API|JOSM_WEBSITE|CACHE_UPDATES|CERTIFICATES|ALL>
	                                          Disable access to the given resource(s), separated by comma
	                                          <OSM API|JOSM website|Cache updates|Certificates|All>

The --download= part of the download option is optional. The arguments --download, --downloadgps and --selection are processed in this order. The value <url-to-xml> can point to a local file with file:relative/path/name.xml. The items in the --offline value are separated by comma.

Java options

They control the Java virtual machine (JVM) and can set 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.

Java system properties options:
      -Djosm.dir.name=JOSM                      Change the JOSM directory name
      -Djosm.pref=/PATH/TO/JOSM/PREF            Set the preferences directory
                                                Default (Linux XDG): /home/name/.config/JOSM
                                                Default (Windows): C:\Users\name\AppData\Roaming\JOSM
      -Djosm.userdata=/PATH/TO/JOSM/USERDATA    Set the user data directory
                                                Default (Linux XDG): /home/name/.local/share/JOSM
                                                Default (Windows): C:\Users\name\AppData\Roaming\JOSM
      -Djosm.cache=/PATH/TO/JOSM/CACHE          Set the cache directory
                                                Default (Linux XDG): /home/name/.cache/JOSM
                                                Default (Windows): C:\Users\name\AppData\Local\JOSM\cache
      -Djosm.home=/PATH/TO/JOSM/HOMEDIR         Set the common directory for preferences,
                                                user data and ./cache/. Lower precedence.
                                                Will get overridden from specific setting.
      -Xmx...m                                  Set maximum Java heap size in megabytes.
                                                May avoid Out-of-Memory errors.

The -Xmx...m option may be useful when Out of Memory errors arise. If you set a common directory with Djosm.home then JOSM will create the subdirectories ./autosave, ./cache and ./validator. If a value has spaces, then enclose it in quotation marks like "josm dev".

When the non-ASCII characters in the command prompt are scrambled, use -Dfile.encoding=Cp850 to receive text from Java in another code page. Which code page is used shows chcp⏎ in the terminal. For UTF-8 on Windows, invoke chcp 65001 in the Windows terminal window before launching JOSM using java -Dfile.encoding=UTF-8 -jar josm.jar

JOSMs Debian package uses -Djosm.dir.name=JOSM-latest to offer parallel installations in the XDG base directories.

Examples for JOSM runjosm options and Java options

# Load three files
  java -jar josm.jar track1.gpx BigBen.jpg "london data.osm"
# Download from OSM according to an URL with zoom and coordinates
  java -jar josm.jar https://www.openstreetmap.org/#map=18/51.501/-0.124
# Download a bounding box and select every element matching a string
  java -jar josm.jar 51.500,-0.126,51.502,-0.122 --selection="Big Ben"
#
# Set directory for JOSM according to a property from the operating system
  java -Djosm.pref=$XDG_CONFIG_HOME -jar josm.jar
# Quotations for a value with space and show JOSMs GUI in English
  java -Djosm.dir.name="josm dev" -jar josm.jar --language=en
# Set the common directory in a sub-subdirectory below the active command prompt
  java -Djosm.home=biketour2017/london -jar josm.jar
# More memory and without phoning home
  java -Xmx1024m --set=message.notifier.enabled=false  -jar josm.jar
#
# Start in an English environment and log debug info plus messages from stderr 
  java -Duser.language=en -jar josm.jar --debug 1>logfile.txt 2>&1

Run-options for Java Web Start

The run-options are read by the javaws command. They control the Web Start mechanism, can encapsulate Java options and can diagnose Java.

# Control 
  -offline                  Allows to Web Start JOSM without internet access

# Encapsulate
  -J<java option>           Supplies the <java option> to the JVM 
  -J-Xmx1024m               Here: Set maximum Java heap size to 1024 megabyte

# Diagnosis
javaws -viewer            Shows the Cache Viewer in the Java Control Panel 
# Allows to opens the Java Control Panel from the command line.

javaws -clearcache        Removes all non-installed applications from the cache
# Equal to 'Delete Files and Applications' from the 'Temporary File Settings' invoked 
# by the 'Settings' button in the 'General' tab of the Java Control Panel.
# javaws -Xclearcache on OpenJDK

The -J run-option takes its part behind the J letter and supplies that as Java option. The jnlp-File used by Web Start offers a second way to set options for JRE and for the JOSM program directly.

The javaws command has some control options on all systems.

The -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.

Other options

The Launcher josm.exe aka Launch4j (only on MS Windows) may give some debug info.

josm.exe --j4l-debug      Tries to write a launch4j.log to current directory
josm.exe --j4l-dont-wait  Ends the wrapper after invoking JOSM.

Command line for Render and Project

JOSM rendering Programm arguments

Usage:
	java -jar josm.jar render <options>

Description:
Renders data and saves the result to an image file.

Options:
	--help|-h                 Show this help
	--input|-i <file>         Input data file name (.osm)
	--output|-o <file>        Output image file name (.png); defaults to 'out.png'
	--style|-s <file>         Style file to use for rendering (.mapcss or .zip)
	                          This option can be repeated to load multiple styles.
	--setting <key>:<value>   Style setting (in JOSM accessible in the style list dialogue right click menu)
	                          Applies to the last style loaded with the --style option.
	--zoom|-z <lvl>           Select zoom level to render. (integer value, 0=entire earth, 18=street level)
	--scale <scale>           Select the map scale
	                          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)
	                          Options --zoom and --scale are mutually exclusive.
	--bounds|-b auto|<min_lon>,<min_lat>,<max_lon>,<max_lat>
	                          Area to render, default value is 'auto'
	                          With keyword 'auto', the downloaded area in the .osm input file will be used (if recorded).
	--anchor <lon>,<lat>      Specify bottom left corner of the rendering area
	                          Used in combination with width and height options to determine the area to render.
	--width-m <number>        Width of the rendered area, in meter
	--height-m <number>       Height of the rendered area, in metres
	--width-px <number>       Width of the target image, in pixels
	--height-px <number>      Height of the target image, in pixels
	--projection <code>       Projection to use, default value 'epsg:3857' (web-Mercator)
	--max-image-size <number> Maximum image width/height in pixel ('0' means no limit), default value: 20000

To specify the rendered area and scale, the options can be combined in various ways:
  * --bounds (--zoom|--scale|--width-px|--height-px)
  * --anchor (--width-m|--width-px) (--height-m|--height-px) (--zoom|--scale)
  * --anchor --width-m --height-m (--width-px|--height-px)
  * --anchor --width-px --height-px (--width-m|--height-m)
If 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.

Examples:
  java -jar josm.jar render -i data.osm -s style.mapcss -z 16
  josm render -i data.osm -s style.mapcss --scale 5000
  josm render -i data.osm -s style.mapcss -z 16 -o image.png
  josm render -i data.osm -s elemstyles.mapcss --setting hide_icons:false -z 16
  josm render -i data.osm -s style.mapcss -s another_style.mapcss -z 16 -o image.png
  josm render -i data.osm -s style.mapcss --bounds 21.151,51.401,21.152,51.402 -z 16
  josm render -i data.osm -s style.mapcss --anchor 21.151,51.401 --width-m 500 --height-m 300 -z 16
  josm render -i data.osm -s style.mapcss --anchor 21.151,51.401 --width-m 500 --height-m 300 --width-px 1800
  josm render -i data.osm -s style.mapcss --scale 5000 --projection epsg:4326

JOSM projection Programm arguments

Usage:
	java -jar josm.jar project <options> <crs> +to <crs> [file]

Description:
Converts coordinates from one coordinate reference system to another.

Options:
	--help|-h         Show this help
	-I                Switch input and output crs
	-r                Switch order of input coordinates (east/north, lon/lat)
	-s                Switch order of output coordinates (east/north, lon/lat)

<crs>:
The format for input and output coordinate reference system is similar to that of the PROJ.4 software.

[file]:
Reads 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.

Examples:
    java -jar josm.jar project +init=epsg:4326 +to +init=epsg:3857 <<<"11.232274 50.5685716"
       => 1250371.1334500168 6545331.055189664

    java -jar josm.jar project +proj=lonlat +datum=WGS84 +to +proj=merc +a=6378137 +b=6378137 +nadgrids=@null <<EOF
    11d13'56.19"E 50d34'6.86"N
    118d39'30.42"W 37d20'18.76"N
    EOF
       => 1250371.1334500168 6545331.055189664
          -1.3208998232319113E7 4486401.160664663