{"id":24293766,"url":"https://github.com/ozguronsoy/simplemapview","last_synced_at":"2026-03-10T03:03:29.285Z","repository":{"id":271172098,"uuid":"912599356","full_name":"ozguronsoy/SimpleMapView","owner":"ozguronsoy","description":"A Qt widget and QML component for rendering online and offline tile-based maps with Python (PySide6) support.","archived":false,"fork":false,"pushed_at":"2026-02-02T00:07:51.000Z","size":2394,"stargazers_count":22,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-02T08:54:16.500Z","etag":null,"topics":["cpp","googlemaps","gui","map","map-widget","offline-maps","openstreetmap","osm","pyside6","python","qml","qt","qt6","qtquick","qtwidgets","tile-map","widget"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ozguronsoy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"ozguronsoy"}},"created_at":"2025-01-06T02:13:03.000Z","updated_at":"2026-02-01T08:07:37.000Z","dependencies_parsed_at":"2025-01-06T03:22:42.499Z","dependency_job_id":"e16e0a7b-64f3-44dd-a793-dcc13d46d483","html_url":"https://github.com/ozguronsoy/SimpleMapView","commit_stats":null,"previous_names":["ozguronsoy/simplemapview"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ozguronsoy/SimpleMapView","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozguronsoy%2FSimpleMapView","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozguronsoy%2FSimpleMapView/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozguronsoy%2FSimpleMapView/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozguronsoy%2FSimpleMapView/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ozguronsoy","download_url":"https://codeload.github.com/ozguronsoy/SimpleMapView/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozguronsoy%2FSimpleMapView/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30322648,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T01:36:58.598Z","status":"online","status_checked_at":"2026-03-10T02:00:06.579Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","googlemaps","gui","map","map-widget","offline-maps","openstreetmap","osm","pyside6","python","qml","qt","qt6","qtquick","qtwidgets","tile-map","widget"],"created_at":"2025-01-16T16:59:35.847Z","updated_at":"2026-03-10T03:03:29.270Z","avatar_url":"https://github.com/ozguronsoy.png","language":"C++","readme":"# SimpleMapView\n\nA Qt widget for rendering tile maps.\n\n- [Setup](#setup)\n- [Map Widget](#map-widget)\n    - [Create Widget](#create-widget)\n    - [Change Tile Server](#change-tile-server)\n    - [Limit Zoom](#limit-zoom)\n    - [Lock Zoom and Geolocation](#lock-zoom-and-geolocation)\n    - [Disable Mouse Events](#disable-mouse-events)\n- [Map Items](#map-items)\n    - [Ellipse](#ellipse)\n    - [Rect](#rect)\n    - [Text](#text)\n    - [Image](#image)\n    - [Lines](#lines)\n    - [Polygon](#polygon)\n- [Markers](#markers)\n    - [Add Marker](#add-marker)\n    - [Change Default Marker Icon](#change-default-marker-icon)\n- [QML](#qml)\n- [Python](#python)\n- [Using Offline Maps](#using-offline-maps)\n\n## Setup\n\n1. create a folder in your project (e.g., ``dependencies/SimpleMapView``) and copy the repo files to the folder.\n2. include ``SimpleMapView`` in your CMake or qmake file. \n\n\nCMake:\n```cmake\nfind_package(Qt6 REQUIRED COMPONENTS Core)\nqt_standard_project_setup()\n\nadd_subdirectory(dependencies/SimpleMapView)\n\nset(CMAKE_AUTORCC ON)\nset(PROJECT_SOURCES\n    # your files\n    dependencies/SimpleMapView/Resources.qrc # optional\n)\n\ntarget_link_libraries(mytarget PUBLIC\n    # your libraries\n    SimpleMapView\n)\n```\n\nqmake:\n```\ninclude(dependencies/SimpleMapView/SimpleMapView.pro)\n```\n\n## Map Widget\n\n### Create Widget\n\ncreate the widget inside the main window's constructor, then set the zoom level and the center coordinates to the place you want to display.\n\n```c++\nSimpleMapView* mapView = new SimpleMapView(this);\nmapView-\u003emove(0, 0);\nmapView-\u003eresize(this-\u003ewidth(), this-\u003eheight()); // full screen\n\nmapView-\u003esetCenter(41.010172, 28.957912); // İstanbul, Türkiye\nmapView-\u003esetZoomLevel(9);\n```\n\n![default_map](readme_images/map.png)\n\n### Change Tile Server\n\nyou can use any tile server that contains ``{x}``, ``{y}``, and ``{z}`` coordinates in the URL.\n\n```c++\nmapView-\u003esetTileServer(TileServers::GOOGLE_MAP);\nmapView-\u003esetTileServer(TileServers::GOOGLE_SAT);\nmapView-\u003esetTileServer(QString(TileServers::AZURE_MAP).replace(\"{api_key}\", \"YOUR_API_KEY\"));\nmapView-\u003esetTileServer(\"https://a.tile.maptiler.com/{z}/{x}/{y}.png?key=YOUR_API_KEY\");\n``` \n![satellite_map](readme_images/map_satellite.png)\n\n### Limit Zoom\n\nyou can set limit (min/max) to zoom level.\n```c++\nmapView-\u003esetMinZoomLevel(10);\nmapView-\u003esetMaxZoomLevel(17);\n```\n\n### Lock Zoom and Geolocation\n\n```c++\nmapView-\u003elockZoom();\nmapView-\u003eunlockZoom();\n\nmapView-\u003elockGeolocation();\nmapView-\u003eunlockGeolocation();\n```\n\n### Disable Mouse Events\n\nby default, you can move the map by holding the left mouse button down and moving the mouse. And you can zoom in/out via the mouse wheel.\n\n```c++\nmapView-\u003edisableMouseWheelZoom();\nmapView-\u003eenableMouseWheelZoom();\n\nmapView-\u003edisableMouseMoveMap();\nmapView-\u003eenableMouseMoveMap();\n```\n## Map Items\n\nmap items are used for drawing on the map.\nAll map items are derived from the ``MapItem`` class.\n\n### Ellipse\n\n```c++\nMapEllipse* ellipse = new MapEllipse(mapView);\n\n//ellipse-\u003esetPosition(QPointF(100, 100));\nellipse-\u003esetPosition(mapView-\u003ecenter());\nellipse-\u003esetAlignmentFlags(Qt::AlignCenter);\nellipse-\u003esetSize(QSizeF(200, 150));\n//ellipse-\u003esetSize(QGeoCoordinate(1e-3, 2e-3));\n\nellipse-\u003esetBackgroundColor(QColor::fromRgba(0xAF0000FF));\nellipse-\u003esetPen(QPen(Qt::black, 3));\n```\n\n### Rect\n\n```c++\nMapRect* rect = new MapRect(mapView);\n\nrect-\u003esetPosition(mapView-\u003ecenter());\nrect-\u003esetSize(QSizeF(200, 150));\n\nrect-\u003esetBorderRadius(8);\nrect-\u003esetBorderRadius(8, 20, 0, 40);\n```\n\n### Text\n\n```c++\nMapText* text = new MapText(mapView);\ntext-\u003esetPosition(mapView-\u003ecenter());\n\n// if size is not set\n// text size will be used.\ntext-\u003esetText(\"Lorem ipsum dolor sit amet.\");\n\ntext-\u003esetFont(QFont(\"Arial\", 14));\ntext-\u003esetTextColor(Qt::white);\ntext-\u003esetTextFlags(Qt::TextSingleLine);\ntext-\u003esetTextPadding(10, 10, 10, 10);\n```\n\n\n### Image\n\n```c++\nMapImage* img = new MapImage(mapView);\n\nimg-\u003esetPosition(mapView-\u003ecenter());\nimg-\u003esetAlignmentFlags(Qt::AlignCenter);\nimg-\u003esetBorderRadius(8);\n\nimg-\u003esetAspectRatioMode(Qt::IgnoreAspectRatio);\nimg-\u003esetImage(QImage(\"image.png\").scaledToWidth(200, Qt::SmoothTransformation));\n//img-\u003esetImage(\"image.png\");\n```\n\n### Lines\n\n```c++\nMapLines* lines = new MapLines(mapView);\nlines-\u003esetPen(QPen(Qt::blue, 5));\n\nlines-\u003epoints().push_back(QPointF(0, 0));\nlines-\u003epoints().push_back(mapView-\u003ecenter());\n```\n\n### Polygon\n\n```c++\nMapPolygon* polygon = new MapPolygon(mapView);\npolygon-\u003esetPen(QPen(Qt::blue, 5));\npolygon-\u003esetBackgroundColor(QColor(255, 0, 0, 50));\n\npolygon-\u003epoints() = {\n\tQPointF(-100, 0),\n\tmapView-\u003ecenter(),\n\tQPointF(-100, mapView-\u003eheight() * 2)\n};\n```\n\n## Markers\n\n### Add Marker\n\n```c++\nMapImage* markerIcon = mapView-\u003eaddMarker(mapView-\u003ecenter());\nmarkerIcon-\u003efindChild\u003cMapText*\u003e()-\u003esetText(\"Marker Text\");\n```\n\n### Change Default Marker Icon\n\n```c++\nmapView-\u003esetMarkerIcon(\":/map_marker_alt.svg\");\n\nQImage newIcon(\":/map_marker_alt.svg\");\n// newIcon.doStuff();\nmapView-\u003esetMarkerIcon(newIcon);\n```\n\n## QML\n\n``SimpleMapView`` provides a QML component based on ``QQuickItem`` instead of ``QWidget``. Since ``QQuickItem`` uses GPU-accelerated rendering, it offers better performance.\n\nTo use the QML component, you need to enable it in your build system first.\n\nCMake:\n```cmake\nset(SIMPLE_MAP_VIEW_BUILD_QML ON)\n```\n\nqmake:\n```\nSIMPLE_MAP_VIEW_BUILD_QML = 1\n```\n\nAfter that you can import and use the QML components in your ``QML`` files.\n\n```qml\nimport QtQuick\nimport QtQuick.Window\nimport QtPositioning\nimport com.github.ozguronsoy.SimpleMapView\n\nWindow {\n    visible: true\n    width: 960\n    height: 540\n    title: \"QtQuickApplication1\"\n\n    SimpleMapView {\n        id: map\n        anchors.fill: parent\n        tileServer: TileServers.GOOGLE_MAP\n        latitude: 37.78310363232004 // Denizli, Türkiye\n        longitude: 29.095721285868844\n        zoomLevel: 14\n\n        MapEllipse {\n            backgroundColor: \"red\"\n            penColor: \"blue\"\n            penWidth: 4\n            position: SimpleMapViewQmlHelpers.createMapPoint(Qt.point(50, 50))\n            size: SimpleMapViewQmlHelpers.createMapSize(Qt.size(150, 100))\n        }\n\n        MapRect {\n            backgroundColor: \"blue\"\n            penColor: \"red\"\n            penWidth: 4\n            position: SimpleMapViewQmlHelpers.createMapPoint(QtPositioning.coordinate(37.77610363232004, 29.065721285868844))\n            size: SimpleMapViewQmlHelpers.createMapSize(QtPositioning.coordinate(0.006, 0.01))\n        }\n\n        Component.onCompleted: {\n            var marker = map.addMarker(map.center)\n            var textItem = SimpleMapViewQmlHelpers.findChild(marker, \"MapText\")\n            if (textItem) {\n                textItem.setText(\"Marker!\")\n            }\n        }\n    }\n}\n\n\n```\n\n\n## Python\n\nTo use ``SimpleMapView`` in ``PySide6`` applications, you have to build and install the **python module** by running ``pip install .`` command on the project's root.\n\nHere is a simple example on how to use in python:\n\n```py\nimport sys\nfrom PySide6.QtWidgets import QApplication\nfrom PySimpleMapView import SimpleMapView, TileServers, MapText\n\napp = QApplication(sys.argv)\n\nmap_view = SimpleMapView()\nmap_view.setTileServer(TileServers.GOOGLE_MAP)\n\nmarker = map_view.addMarker(map_view.center())\nmarker.findChild(MapText).setText(\"Marker\")\n\nmap_view.resize(1280, 720)\nmap_view.show()\n\nsys.exit(app.exec())\n```\n\n## Using Offline Maps\n\nCreate a widgets app and download the tiles. This is a one time thing.\n```c++\nSimpleMapView* mapView = new SimpleMapView(this);\n\n// Eskişehir, Türkiye\nconst QGeoCoordinate topLeft(39.86073417201014, 30.292027040985936);\nconst QGeoCoordinate bottomRight(39.68314525072665, 30.719807145290957);\nconst int zoomLevel1 = 10;\nconst int zoomLevel2 = 15;\n\nmapView-\u003edownloadTiles(\"path/to/offline-tiles\", topLeft, bottomRight, zoomLevel1, zoomLevel2);\n```\n\nUse downloaded tiles\n```c++\nSimpleMapView* mapView = new SimpleMapView(this);\nmapView-\u003esetTileServer(\"path/to/offline-tiles\");\n// mapView-\u003esetTileServer(\":/SimpleMapView/Tiles\");\n```\n\n``downloadTiles`` method also generates a ``qrc`` file so one can use the resource system. However, this is not recommended for large maps, as it increases compile time and can significantly bloat the executable.\n","funding_links":["https://github.com/sponsors/ozguronsoy"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fozguronsoy%2Fsimplemapview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fozguronsoy%2Fsimplemapview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fozguronsoy%2Fsimplemapview/lists"}