Difference between revisions of "LazMapViewer"

From Lazarus wiki
(Add screenshot of demo program)
(About: Getting started)
Line 38: Line 38:
 
| lazmapviewer_bgra.lpk            || TMvBGRADrawingEngine        || Alternative drawing engine based on the BGRABitmap package
 
| lazmapviewer_bgra.lpk            || TMvBGRADrawingEngine        || Alternative drawing engine based on the BGRABitmap package
 
|}
 
|}
 +
 +
==Getting Started==
 +
Here is a short tutorial to create your first map.
 +
 +
===Preparation===
 +
* Drop a <tt>TMapView</tt> component on the form and size it as needed. The component is on the ''Misc'' tab of the Lazarus component palette.
 +
* Add this handler for the form's <tt>OnShow</tt> or <tt>OnActivate</tt> event and set the <tt>Active</tt> property of the <tt>MapView</tt> component to <tt>true</tt>; in principle, this should be possible also in the object inspectore, however, does not work at the time of this writing.
 +
<syntaxhighlight lang=Pascal>
 +
procedure TForm1.FormActivate(Sender: TObject);
 +
begin
 +
  MapView1.Active := true;
 +
end; </syntaxhighlight>
 +
* That's all. Compile, run and see your fist map!
 +
* In the background the <tt>MapView</tt> component has established an internet connection to the default map provider and downloaded the default map. The maps are delivered as a series of '''tiled images''' at given size, usually 256x256 pixels, and usually in png format. They are stored in a cache directory (property <tt>CachePath</tt>) and used primarily to reduce internet traffic; only when an image is not found another download from the internet is triggered again.
 +
 +
===Magnification===
 +
* The map images are provided in different magnifications depending on the <tt>Zoom</tt> level of the <tt>MapView</tt>. Each step in <tt>Zoom</tt> level corresponds to doubling the magnification. The maximum <tt>Zoom</tt> level for most map providers is 18 -- this means that the most detailed maps cover a fraction of <tt>1/2^18</tt> of the earth circumference, about 150 m.
 +
* So, if you want to see '''more details''' you must increase the <tt>Zoom</tt> value of the <tt>MapView</tt>. You can enter the requested value in the Object Inspector, or add a <tt>TScrollbar</tt> or <tt>TTrackbar</tt> to the form to change the magnfication interactively by using the following simple <tt>OnChange</tt> event handler (set the <tt>Max</tt> of the bar to, say, 18:
 +
<syntaxhighlight lang=Pascal>
 +
procedure TForm1.TrackBar1Change(Sender: TObject);
 +
begin
 +
  MapView1.Zoom := TrackBar1.Position;
 +
end;</syntaxhighlight>
 +
 +
===Location===
 +
* By default the '''center of the map''' is the intersection of the 0-degree meridian with the equator - which is a bit off of the coast of western Africa. In order to focus onto a different location you must specify its longitude and latitude in the <tt>Center</tt> property of the <tt>MapView</tt>. This is a <tt>TRealPoint</tt> record having the longitude and latitude in the <tt>Lon</tt> and <tt>Lat</tt> record elements.
 +
* Suppose we want to zoom into Manhattan. Use your favorite search engine to determine the geo coordinates of Manhattan: Longitude = -73.985130°, Latitude = 40.758896°. Alternatively you can also use the <tt>TGeoNames</tt> component which comes with the LazMapViewer package and provides access to a database of the geo coordinates of a huge number of locations via internet.
 +
<syntaxhighlight lang=Pascal>
 +
procedure TForm1.FormActivate(Sender: TObject);
 +
var
 +
  P: TRealPoint;
 +
begin
 +
  MapView1.Active := true;
 +
  P.Lon := -73.985130;
 +
  P.Lat := 40.758896;
 +
  MapView1.Center := P;
 +
end; </syntaxhighlight>
 +
* In addition to specifying the location numerically the you can also change location by '''dragging the map with the mouse'''. Just press the left mouse button and slowly move the mouse in the direction where you want to see more - the map will follow. But you should be aware that usually neighboring maps will have to be loaded from the internet, and this makes the entire action a bit sluggish.

Revision as of 23:07, 1 January 2021

lazmapviewer.png

About

LazMapViewer is a component for embedding maps obtained from the internet, such as Google maps or OpenStreetView, into a Lazarus form.

Authors

The initial version of the package was written by Maciej Kaczkowski and later improved by members of the Lazarus forum.

License

Modified LGPL (with linking exception, like Lazarus LCL)

Download and Installation

Development version

Use an svn client to download the current trunk version from svn://svn.code.sf.net/p/lazarus-ccr/svn/components/lazmapviewer. Alternatively download the zipped snapshot from https://sourceforge.net/p/lazarus-ccr/svn/HEAD/tree/components/lazmapviewer/ and unzip it to some folder.

Release version

Occasionally, release versions are made available via the Online Package Manager for easy one-click-installation directly from Lazarus.

Installation

In Lazarus, go to "Package" > "Open Package File .lpk". Navigate to the folder with the LazMapViewer sources, and select lazmapviewerpkg.lkp. Click "Compile", then "Use" > "Install". This will rebuild the IDE (it may take some time). When the process is finished the IDE will restart, and you'll find the MapViewer in the palette Misc.

There are optional, supporting packages to extend the basic functionality. They must be installed in the same way, after lazmapviewerpkg.lpk.

Package file name contained components purpose
lazmapviewerpkb.lpk TMapView main component to display maps
TMvGeoNames access to geo coordinates of cities
TMvDEFpc default download engine using the internal fpc routines
lazmapviewer_synapse.lpk TMvDESynapse alternative download engine based on the Synapse library
lazmapviewer_rgbgraphics.lpk TMvRGBGraphicsDrawingEngine Alternative drawing engine based on the RGBGraphics package
lazmapviewer_bgra.lpk TMvBGRADrawingEngine Alternative drawing engine based on the BGRABitmap package

Getting Started

Here is a short tutorial to create your first map.

Preparation

  • Drop a TMapView component on the form and size it as needed. The component is on the Misc tab of the Lazarus component palette.
  • Add this handler for the form's OnShow or OnActivate event and set the Active property of the MapView component to true; in principle, this should be possible also in the object inspectore, however, does not work at the time of this writing.
procedure TForm1.FormActivate(Sender: TObject);
begin
  MapView1.Active := true;
end;
  • That's all. Compile, run and see your fist map!
  • In the background the MapView component has established an internet connection to the default map provider and downloaded the default map. The maps are delivered as a series of tiled images at given size, usually 256x256 pixels, and usually in png format. They are stored in a cache directory (property CachePath) and used primarily to reduce internet traffic; only when an image is not found another download from the internet is triggered again.

Magnification

  • The map images are provided in different magnifications depending on the Zoom level of the MapView. Each step in Zoom level corresponds to doubling the magnification. The maximum Zoom level for most map providers is 18 -- this means that the most detailed maps cover a fraction of 1/2^18 of the earth circumference, about 150 m.
  • So, if you want to see more details you must increase the Zoom value of the MapView. You can enter the requested value in the Object Inspector, or add a TScrollbar or TTrackbar to the form to change the magnfication interactively by using the following simple OnChange event handler (set the Max of the bar to, say, 18:
procedure TForm1.TrackBar1Change(Sender: TObject);
begin
  MapView1.Zoom := TrackBar1.Position;
end;

Location

  • By default the center of the map is the intersection of the 0-degree meridian with the equator - which is a bit off of the coast of western Africa. In order to focus onto a different location you must specify its longitude and latitude in the Center property of the MapView. This is a TRealPoint record having the longitude and latitude in the Lon and Lat record elements.
  • Suppose we want to zoom into Manhattan. Use your favorite search engine to determine the geo coordinates of Manhattan: Longitude = -73.985130°, Latitude = 40.758896°. Alternatively you can also use the TGeoNames component which comes with the LazMapViewer package and provides access to a database of the geo coordinates of a huge number of locations via internet.
procedure TForm1.FormActivate(Sender: TObject);
var
  P: TRealPoint;
begin
  MapView1.Active := true;
  P.Lon := -73.985130;
  P.Lat := 40.758896;
  MapView1.Center := P;
end;
  • In addition to specifying the location numerically the you can also change location by dragging the map with the mouse. Just press the left mouse button and slowly move the mouse in the direction where you want to see more - the map will follow. But you should be aware that usually neighboring maps will have to be loaded from the internet, and this makes the entire action a bit sluggish.