% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/map.R
\name{mapScalebar}
\alias{mapScalebar}
\title{Add a Scalebar to a Map}
\usage{
mapScalebar(
  x,
  y = NULL,
  length,
  lwd = 1.5 * par("lwd"),
  cex = par("cex"),
  col = "black",
  debug = getOption("oceDebug")
)
}
\arguments{
\item{x, y}{position of the scalebar.  Eventually these two items may be
handled similarly to the corresponding arguments in \code{\link[=legend]{legend()}}, but at the
moment \code{y} must be \code{NULL} and \code{x} must be \code{"top"}, \code{"topleft"} or
\code{"topright"}.}

\item{length}{the distance to indicate, in kilometres.  If not provided, a
reasonable choice is made, based on the existing plot.}

\item{lwd}{line width of the scalebar.}

\item{cex}{character expansion factor for the scalebar text.}

\item{col}{color of the scalebar.}

\item{debug}{an integer specifying whether debugging information is
to be printed during the processing. This is a general parameter that
is used by many \code{oce} functions. Generally, setting \code{debug=0}
turns off the printing, while higher values suggest that more information
be printed. If one function calls another, it usually reduces the value of
\code{debug} first, so that a user can often obtain deeper debugging
by specifying higher \code{debug} values.}
}
\description{
Draw a scalebar on a map created by \code{\link[=mapPlot]{mapPlot()}} or \code{\link[=plot,coastline-method]{plot,coastline-method()}}.
For plots made otherwise, see \sQuote{Details}.
}
\details{
It is also possible to use this with any plot, but the results will
only make sense if the aspect ratio is set properly so that an item that is
circular in nature is (very closely) circular on the plot. This aspect ratio
condition is met by both \code{\link[=mapPlot]{mapPlot()}} and \code{\link[=plot,coastline-method]{plot,coastline-method()}}.

The scale is appropriate to the centre of the plot, and will become
increasingly inaccurate away from that spot, with the error depending on the
projection and the fraction of the earth that is shown.
}
\examples{
\donttest{
library(oce)
data(coastlineWorld)
# Arctic Ocean
par(mar = c(2.5, 2.5, 1, 1))
mapPlot(coastlineWorld,
    latitudelim = c(60, 120), longitudelim = c(-130, -50),
    col = "lightgray", projection = "+proj=stere +lat_0=90"
)
mapScalebar()
}


}
\seealso{
Other functions related to maps: 
\code{\link{formatPosition}()},
\code{\link{lonlat2map}()},
\code{\link{lonlat2utm}()},
\code{\link{map2lonlat}()},
\code{\link{mapArrows}()},
\code{\link{mapAxis}()},
\code{\link{mapContour}()},
\code{\link{mapCoordinateSystem}()},
\code{\link{mapDirectionField}()},
\code{\link{mapGrid}()},
\code{\link{mapImage}()},
\code{\link{mapLines}()},
\code{\link{mapLocator}()},
\code{\link{mapLongitudeLatitudeXY}()},
\code{\link{mapPlot}()},
\code{\link{mapPoints}()},
\code{\link{mapPolygon}()},
\code{\link{mapText}()},
\code{\link{mapTissot}()},
\code{\link{oceCRS}()},
\code{\link{oceProject}()},
\code{\link{shiftLongitude}()},
\code{\link{usrLonLat}()},
\code{\link{utm2lonlat}()}
}
\author{
Dan Kelley
}
\concept{functions related to maps}
