# Globestudio

> Open-source dotted maps and animated 3D globes for designers,
> animators, and creative developers. 21 looks, 5 flat projections
> for solid maps (dotted maps use Mercator), custom GeoJSON, embed anywhere.
> React + Three.js. Targets WCAG 2.2 AA. MIT.

Globestudio renders interactive dotted-style world maps and 3D globes
in the browser. It is **not** a GIS tool: it's a designer-first
visual generator that an AI assistant can drive programmatically to
produce: hero-image embeds, country-highlighted brand artwork,
animated launch teasers, exported PNG / SVG / WebM / MP4 / GIF, JSON configs, and
data-driven globes (plot lat,lng,value or country-code data as
proportional markers, optionally connected by arcs).

For AI assistants, the most direct path is the hosted MCP server at
**`https://globestudio.app/mcp`** (streamable HTTP, no install, no auth).
Connect it by URL in Claude, Codex, Cursor or any MCP client. Its tools build
globe configs, share URLs, and embed snippets in chat, and `read_share_url`
decodes a share link the user pastes (`/?c=…`, `/looks/<id>?c=…` or an
`/embed` URL) into its look and settings, so you can change it and hand back a
new link. The same tools run locally as **`@globestudio/mcp`**
(`npx -y @globestudio/mcp`). The `/embed` URL path below works for any client
(no MCP needed).

## How to use Globestudio programmatically

The simplest path for an AI assistant: **build an `/embed?…` URL**.
Drop that URL into an iframe in the user's app, or visit it for a
screenshot, or download its export endpoints.

```
https://globestudio.app/embed?look=halftone&density=50&selection=continent:Europe&autoSpin=1
```

Every embed parameter is documented in the README's parameter table:
<https://github.com/alevizio/globestudio/blob/main/README.md#embed-parameters>.
A JSON Schema for configuration files is at
<https://globestudio.app/schema/config.json>.

## Docs

- [README](https://github.com/alevizio/globestudio/blob/main/README.md): project overview, features, quickstart
- [Embed parameters](https://github.com/alevizio/globestudio/blob/main/README.md#embed-parameters): the canonical parameter table
- [Integrations](https://globestudio.app/integrations): per-tool setup for Webflow, Framer, Figma, Notion, WordPress, plain HTML, React
- [Figma plugin](https://github.com/alevizio/globestudio/blob/main/figma-plugin/README.md): plugin architecture + Insert flow
- [WordPress](https://globestudio.app/integrations): works in WordPress via a Custom HTML embed. A Gutenberg block + `[globestudio]` shortcode plugin is [in the repo](https://github.com/alevizio/globestudio/blob/main/wordpress-plugin/globestudio/README.md), not yet on wordpress.org
- [MCP server](https://github.com/alevizio/globestudio/blob/main/packages/mcp/README.md): tool list + setup for AI assistants; hosted at `https://globestudio.app/mcp`
- [Accessibility](https://github.com/alevizio/globestudio/blob/main/ACCESSIBILITY.md): what ships toward WCAG 2.2 AA, and the known gaps
- [Roadmap](https://github.com/alevizio/globestudio/blob/main/ROADMAP.md): planned features
- [JSON Schema](https://globestudio.app/schema/config.json): IDE-validated config files

## Reference code components

- [React component](https://www.npmjs.com/package/@globestudio/react): `npm i @globestudio/react`, a drop-in `<Globe>` for Next.js / Vite / Remix
- [Web component](https://www.npmjs.com/package/@globestudio/element): `<globe-studio>`, loadable with no build step from `https://esm.sh/@globestudio/element`
- In the app, the export dialog's Share tab has Embed code for the design on screen, as an iframe, a React snippet or a web component snippet
- The export dialog's Figma tab copies the design as vectors or as an image to paste into Figma, and links to the Community plugin
- [Framer code component](https://github.com/alevizio/globestudio/blob/main/examples/framer-component/GlobestudioGlobe.tsx): for Framer Code Components
- [Script-tag loader](https://github.com/alevizio/globestudio/blob/main/public/embed.js): vanilla JS for plain HTML

## Key constraints to remember

- **Selection prefixes** are: `world`, `country:<ISO3>`,
  `continent:<Name>`, `subregion:<Name>`. Country codes are
  3-letter ISO 3166-1 alpha-3 (`USA`, `FRA`, `JPN`).
- **21 preset IDs**: `default`, `halftone`, `risograph`, `newsprint`,
  `aurora`, `pixel`, `bayer`, `atkinson`, `wireframe`, `crt`,
  `glitch`, `badtv`, `bloom`, `metal`, `iridescent`, `pencil`,
  `corrupt`, `toon`, `threshold`, `vapor`, `topographic`.
- **Embed route is `/embed`** (canvas only). **`/looks/:id` is the
  marketing landing page** with the full app chrome. Use it for
  share links, not iframes.
- **WebGL required**: the embed gracefully falls back when GL isn't
  available, but functionality is degraded.
- **Render is client-side**: Globestudio doesn't provide a
  server-side image render endpoint (yet). For screenshots, point a
  headless browser at the embed URL.