VisQuill Lens
User Tutorial
Everything you need to load your geographic data, configure the visual, and share your results.
What is VisQuill Lens?
Overview — Basic functionality of VisQuill Lens
Click to load from YouTubeVisQuill Lens is an interactive map visual that lets you explore geographic data by dragging circular lenses across a map. Each lens aggregates the data underneath it and displays a chart — giving you an immediate spatial picture of how values vary across a region.
It is available as a custom visual for Microsoft Power BI and as a standalone web application at visquill.com/visuals.
Quick Start
Getting Started — Loading a dataset and configuring a lens
Click to load from YouTubeWhen you open the standalone app, a London example dataset is loaded automatically — showing the distribution of cafés, fast food outlets, and grocery stores across the city. You will immediately see a working visual you can interact with.
Drag the lens circles across the map to explore different neighbourhoods. Notice how the chart inside each lens changes as it moves — comparing the food environment in areas like the City, Shoreditch, or Notting Hill.
Click Change data in the top bar when you are ready to load your own data.
Preparing Your Data
The golden rule: use absolute numbers
VisQuill Lens aggregates values spatially — it sums everything inside the lens circle. This means you must use absolute counts, not percentages or rates.
The Stockholm example datasets below use this correctly — each row represents one point of interest, with a 1 in the column matching its category and 0 in all others. When the lens moves over an area, it sums those 1s to tell you how many of each type are there.
Column names
VisQuill Lens automatically detects your coordinate columns. For the best experience, name your columns clearly. The visual recognises these patterns:
| Column | Recognised names |
|---|---|
| Latitude | lat, latitude, breite, breitengrad |
| Longitude | lng, lon, long, longitude, länge, längengrad |
| Location ID | id, location_id, loc_id, ags, key, code, nr |
If your column names are not recognised automatically, you can assign them manually in the column mapping step of the data loading wizard.
59.3263 for latitude and 18.0840 for longitude. Latitudes must be between −90 and 90, longitudes between −180 and 180.File format
VisQuill Lens accepts CSV files. Most spreadsheet applications can export to CSV via File → Save As or File → Export. Tab-separated and semicolon-separated files are also supported — you can select the separator in the wizard after loading.
Your data never leaves your computer. All files are processed locally in your browser — nothing is uploaded to any server.
Example datasets — Stockholm
Three CSV files covering Stockholm from OpenStreetMap — restaurants, shops, and tourism. Download them to use as a reference or to try the loading workflow yourself. Together they demonstrate the multiple flat files mode, with one file per lens.
restaurants.csv shops.csv tourism.csvEach file has its own coordinates and a set of binary category columns:
restaurants.csv — cuisine categories
| lat | lng | name | Asian | European | Mid. Eastern | American | African | Other |
|---|---|---|---|---|---|---|---|---|
| 59.3053 | 17.9633 | Marino | 0 | 1 | 0 | 0 | 0 | 0 |
| 59.3284 | 18.0631 | Tegelbacken | 0 | 0 | 0 | 0 | 0 | 1 |
shops.csv — retail categories
| lat | lng | name | Food | Fashion | Health/Beauty | Home | Leisure |
|---|---|---|---|---|---|---|---|
| 59.3428 | 18.0367 | Cykelringen | 0 | 0 | 0 | 0 | 1 |
| 59.3372 | 18.0911 | ICA Karlaplan | 1 | 0 | 0 | 0 | 0 |
tourism.csv — attraction categories
| lat | lng | name | Museum | Gallery | Public Art | Nature | Entertainment |
|---|---|---|---|---|---|---|---|
| 59.3249 | 18.0706 | Gamla stan | 0 | 0 | 0 | 0 | 1 |
| 59.3263 | 18.0840 | Moderna museet | 1 | 0 | 0 | 0 | 0 |
Loading Your Data
Click Change data in the top bar to open the data wizard. The wizard guides you through the process in three steps.
Choose how you want to load data
Select from CSV upload, load a saved session, or browse example datasets.
Choose your data structure
Tell the wizard how your CSV files are organised — one of three options below.
Upload and map your columns
Drop your files, confirm the column assignments, and click Load data.
Option 1 — Single flat table
One CSV file containing coordinates and all data columns together. All measure columns are assigned to Lens 1 automatically. This is the simplest option — use it when all your data is in one file.
| lat | lng | Museum | Gallery | Nature | Entertainment |
|---|---|---|---|---|---|
| 59.3263 | 18.0840 | 1 | 0 | 0 | 0 |
| 59.3655 | 18.0710 | 0 | 0 | 1 | 0 |
Option 2 — Multiple flat files
Up to three CSV files, each containing their own coordinates and data columns — one file per lens. No shared ID is needed. This is the format used by the three Stockholm datasets — each file maps directly to one lens.
| File | Lens | Columns |
|---|---|---|
| restaurants.csv | Lens 1 | Asian, European, Mid. Eastern, American, African, Other |
| shops.csv | Lens 2 | Food, Fashion, Health/Beauty, Home, Leisure |
| tourism.csv | Lens 3 | Museum, Gallery, Public Art, Nature, Entertainment |
Option 3 — Separate tables
A locations file with coordinates plus up to three data files — one per lens — joined by a shared location ID. Use this when your data files do not contain coordinates but share a common identifier with your locations table.
locations.csv
| id | lat | lng |
|---|---|---|
| district-1 | 51.5074 | -0.1278 |
| district-2 | 53.4808 | -2.2426 |
data.csv → Lens 1
| id | 0–17 | 18–64 | 65+ |
|---|---|---|---|
| district-1 | 12400 | 48200 | 9800 |
| district-2 | 18700 | 71300 | 14200 |
Configuring the Visual
Click Configure in the top bar to open the configuration panel.
Fields tab
Assign your data columns to lenses. Click a column in the available list, then click the lens slot you want to assign it to. You can assign multiple columns to one lens — each becomes one bar in the chart. You can also move columns between lenses or remove them.
Map tab
Choose your map style from built-in providers — CartoDB, OpenStreetMap, Stadia, and others. You can also enter a custom tile URL. Set the home position by clicking Set current view as home.
Visual tab
Control the overall appearance — background mask (glass pane), title and subtitle, and whether data points are shown as dots on the map.
Lens tabs
Each active lens has its own tab for detailed configuration:
- Colors — set each bar's color individually or apply a gradient from a base color
- Scale — linear or square root scaling for bar heights
- Labels — show or hide category labels, value labels, and grid lines
- Rim — adjust rim radius and baseline appearance
AI Assistance tab
Write a natural language instruction — for example "use warm tones for restaurants and show value labels" — then download or copy the generated prompt and paste it into any AI assistant such as Claude or ChatGPT. Paste the response back to apply the changes automatically.
Configure with AI in Under 2 Minutes
Click to load from YouTubeSaving & Exporting
Save a session
Click Save in the top bar to save your session as a .json file. This includes your data and all configuration. Load it again later via Change data → Load saved session, or share it with a colleague.
Export for the web
Click Export to produce a standalone web viewer as a zip file. Deploy it to any static host — no server-side code required.
Netlify
Go to netlify.com/drop and drag the unzipped folder onto the page. Your visual is live in seconds.
GitHub Pages
Push the files to a repository and enable Pages in Settings.
Preview locally
Open a terminal in the unzipped folder and run:
python3 -m http.server 8080
Then open http://localhost:8080 in your browser.
Using VisQuill Lens in Power BI
Using the VisQuill Lens custom visual in Power BI
Click to load from YouTubeDownload the .pbiviz file from visquill.com/visuals and import it via Insert → More visuals → Import a visual from a file. The evaluation version is fully functional — try it directly with your own data.
Data roles
- Latitude — a numeric latitude field
- Longitude — a numeric longitude field
- Location — optional text field used as a unique identifier
- Lens 1, Lens 2, Lens 3 — numeric measure fields, one set per lens
Configuration and presentation mode
The configuration panel works exactly as described above. In Power BI, your configuration is automatically saved with the report. Enable Presentation mode in the Format pane to hide the configuration toggle when sharing reports with end users.
Troubleshooting
No data appears on the map
- Check that latitude and longitude columns are correctly assigned in the column mapping step
- Verify coordinates are in decimal degrees, not degrees/minutes/seconds
- Check that latitude values are between −90 and 90 and longitude values are between −180 and 180
The lens shows zero or unexpected values
- Make sure you are using absolute counts, not percentages or rates
- Check that columns are assigned to the correct lens in the Fields tab
- Try increasing the lens radius — the area may contain fewer locations than expected
Map tiles are not loading
- Check your internet connection — tiles are loaded from third-party providers
- Some providers require an API key — check the Map tab
- Try switching to a different map style
My CSV file is not loading correctly
- Check that the separator matches — use the separator selector below the drop zone
- Make sure the file is saved in UTF-8 encoding if it contains special characters
- Check there are no empty rows at the top before the header row
Getting Help
For questions, feedback, or assistance with your specific use case, contact contact@visquill.com.
More about pricing and licensing at visquill.com/visuals.