This page is in development. What is written below is accurate, but the page is not finished and will gain content in a coming release.
MapCore CLI
An early tool, and Windows-only. Its source is in the MapCore repository under
MapCore/Tools/CLI and it is not part of the SDK installer — ask your MapCore
representative for it. Commands and flags may change.
mapcore-cli drives the SDK from a shell. Each command maps onto exactly one API method,
with that method's real parameters, and the tool can render the current viewport straight to an
image file. So you can build a map step by step from a terminal, capture what it looks like, and
never compile anything.
That makes it useful for three things a program is a clumsy way to do: checking that a data source loads and looks right, reproducing a bug as a list of commands somebody else can replay, and letting an automated agent issue calls and then look at the result.
Host and client
The tool is one process in two roles.
The host owns the SDK and a window, on a single UI thread, and stays running. Each client invocation is a short-lived process that sends one command to the host over a loopback TCP port and exits with the result.
mapcore-cli <command> mapcore-cli init
(client, exits) ──── TCP 127.0.0.1:5000 ────▶ (host: window + SDK, renders PNGs)
◀─── OK / ERROR <code> ─────
That split is what makes the SDK's threading rules hold: every SDK object is created and touched on the host's UI thread and nowhere else. The listener thread only queues the command and wakes the UI thread. See Threading and lifecycle for why that matters.
Start the host
.\mapcore-cli.exe init --width 1024 --height 768
It blocks while serving. The window is hidden by default — headless — so add --show to watch
it. --port defaults to 5000, so every later command can omit it; pass it only to run several
hosts at once.
Note that init does not create the device. That is Dev-Create, so the device's own
parameters stay yours to choose.
init flag | Default |
|---|---|
--port <p> | 5000 |
--width <w> | 1024 |
--height <h> | 768 |
--show | hidden (headless) |
--log <file> or --log none | mapcore-cli-<port>.log |
A map on screen
Run these from the folder holding mapcore-cli.exe, one at a time. Each line is one API call:
.\mapcore-cli.exe Dev-Create device
.\mapcore-cli.exe Raster-Create r1 D:\Maps\swiss\Raster\Kerl-100K
.\mapcore-cli.exe Raster-GetCoordinateSystem r1 cs1
.\mapcore-cli.exe Terrain-Create t1 cs1 r1
.\mapcore-cli.exe Om-Create om1 cs1
.\mapcore-cli.exe Vp-Create v1 device cs1 om1 t1 mapType=2d
.\mapcore-cli.exe Vp-SetCameraPosition v1 816659 4716770 0
.\mapcore-cli.exe Vp-SetCameraScale v1 130
.\mapcore-cli.exe Vp-Render v1
.\mapcore-cli.exe Vp-HasPendingUpdates v1
.\mapcore-cli.exe Vp-Render v1
.\mapcore-cli.exe Vp-RenderScreenRectToBuffer v1 swiss.png
.\mapcore-cli.exe shutdown
That is the same sequence as the Quickstart, one shell line per step.
Rendering is explicit and nothing is drawn until you ask. There is no background or timer
render, so with --show even the visible window updates only when you call Vp-Render. Because
tiles load asynchronously, one render is rarely the finished picture: repeat Vp-Render until
Vp-HasPendingUpdates reports pending=false, then capture. Vp-RenderScreenRectToBuffer
accepts settle=1 to run that loop for you.
Named objects instead of pointers
Every *-Create command stores the object it made in a registry under the name you give it, and
later commands pass that name. That is how an API full of pointer parameters becomes typeable:
Terrain-Create t1 cs1 r1 is IMcMapTerrain::Create with the coordinate system and the layer it
already made.
list shows what is registered; release <name> drops one.
The commands
The prefix names the interface, so a command tells you which one to read in the API reference:
| Prefix | Interface |
|---|---|
Dev- | IMcMapDevice |
Raster- | IMcNativeRasterMapLayer |
Terrain- | IMcMapTerrain |
Om- | IMcOverlayManager |
Vp- | IMcMapViewport, including its IMcMapCamera methods |
Overlay-, LineItem-, Scheme-, Object- | The overlay object chain |
Required arguments are positional in API order; optional ones are key=value tokens in any
order, which keeps the client's --flag parsing from eating them. A response is one line, OK …
or ERROR <code> <message>, and the client's exit code is 0 only on OK — so a script can
check it.
There are no bundled shortcuts: no command performs two API calls. That is deliberate, and it is what makes a command log a faithful record of the calls a program would have to make.
| Command | Calls |
|---|---|
Dev-Create <name> [renderSystem=…] [logging=…] | IMcMapDevice::Create. renderSystem is one of auto, d3d9, d3d11, gl, gl3, none; logging one of none, low, medium, high |
Raster-Create <name> <dir> [firstLowerQualityLevel=N] [missingFiles=0] [numLevelsToIgnore=0] [enhanceBorderOverlap=0] | IMcNativeRasterMapLayer::Create |
Raster-GetBoundingBox <layer> | GetBoundingBox |
Raster-GetCoordinateSystem <layer> <out-cs-name> | GetCoordinateSystem |
Terrain-Create <name> <coordSys> <layer> [layer…] | IMcMapTerrain::Create. Passing - for the coordinate system takes it from the first layer |
Om-Create <name> <coordSys> | IMcOverlayManager::Create |
Om-InitializeSymbologyStandardSupport <om> [standard=app6d|2525c|none] [showGeoMetric=0] [ignoreNonExistent=1] | InitializeSymbologyStandardSupport |
Vp-Create <name> <device> <coordSys> <om> <terrain> [terrain…] [mapType=2d|3d] | IMcMapViewport::Create, bound to the host window |
Vp-Render <vp> | Render, then reports pending= |
Vp-HasPendingUpdates <vp> [type=…] | HasPendingUpdates |
Vp-PerformPendingUpdates <vp> [type=…] [timeout=30000] | PerformPendingUpdates |
Vp-SetCameraPosition <vp> <x> <y> <z> [relative=0] | SetCameraPosition |
Vp-GetCameraPosition <vp> | GetCameraPosition |
Vp-SetCameraScale <vp> <unitsPerPixel> [point=x,y,z] | SetCameraScale |
Vp-GetCameraScale <vp> | GetCameraScale |
Vp-SetBackgroundColor <vp> <r> <g> <b> <a> | SetBackgroundColor, each 0–255 |
Vp-GetViewportSize <vp> | GetViewportSize |
Vp-ViewportResized <vp> | ViewportResized |
Vp-SetRenderToBufferMode <vp> <0|1> | SetRenderToBufferMode |
Vp-GetRenderToBufferNativePixelFormat <vp> | GetRenderToBufferNativePixelFormat |
Vp-RenderScreenRectToBuffer <vp> <out-file> [rect=l,t,r,b] [size=w,h] [format=…] [settle=1] | RenderScreenRectToBuffer, then IMcImage::Save |
Overlay-Create <name> <om> [internal=0] | IMcOverlay::Create |
LineItem-Create <name> [target=screen|world] [style=…] [color=r,g,b,a] [width=10] | IMcLineItem::Create |
Scheme-Create <name> <om> <item> [coord=world|screen|image] | IMcObjectScheme::Create |
Object-Create <name> <overlay> <scheme> <x,y,z> [x,y,z …] | IMcObject::Create |
list, release <name>, ping, shutdown, help | The host and its registry |
mapcore-cli --help prints the list, and mapcore-cli <command> --help prints one command's
parameters and defaults. Both work with no host running.
Drawing over the map
Continuing from the viewport above — the overlay chain is four objects, in this order:
.\mapcore-cli.exe Overlay-Create ov1 om1
.\mapcore-cli.exe LineItem-Create line1 color=255,0,255,255 width=10
.\mapcore-cli.exe Scheme-Create sc1 om1 line1 coord=world
.\mapcore-cli.exe Object-Create obj1 ov1 sc1 800000,4710000,0 816659,4716770,0 830000,4725000,0
.\mapcore-cli.exe Vp-Render v1
.\mapcore-cli.exe Vp-RenderScreenRectToBuffer v1 line.png
An item describes how to draw, a scheme binds the item to a coordinate space, and an object places it at real coordinates inside an overlay — the overlay model itself, in four commands.
The interactive shell
.\mapcore-cli.exe shell
MapCore CLI shell -- port 5000. Tab completes commands and object names; 'help' for commands, 'exit' to quit.
mapcore> Vp-SetCa⇥
mapcore> Vp-SetCameraScale v1 130
OK scale set
Tab completes the command name on the first token, and a registered object name on later ones — so it reads the live registry, not just a static list. A single match fills in; several are listed with their shared prefix filled.
When stdin is a pipe rather than a console it reads commands line by line instead, which makes a scenario file runnable:
Get-Content scenario.txt | .\mapcore-cli.exe shell
Two helpers back the completion and work without a host: commands prints every command name,
complete <prefix> prints the matches for a prefix.
Record and replay
The host logs every command it runs to mapcore-cli-<port>.log, in the directory init was
launched from — --log <file> moves it, --log none turns it off. Each line is a ready-to-run
client invocation, so the log is the reproduction:
# MapCore CLI command log -- replayable. Start the host first:
# & "…\mapcore-cli.exe" init --port 5010 --width 800 --height 600 --log none
& "…\mapcore-cli.exe" Raster-Create r1 "D:\Maps\swiss\Raster\Kerl-100K" --port 5010
To replay, start a fresh host on the same port with --log none — otherwise it overwrites the
log you are replaying — and run the file. shutdown, ping and help are not recorded, and the
embedded --port is the recording session's, so replay on that port or find-and-replace it.
Build it
Windows and x64 only; the build stops with an error on any other platform. It compiles against an
installed SDK, expecting the CLI folder to sit beside the SDK's own directory:
cmake -S CLI -B CLI\build -A x64
cmake --build CLI\build --config Release
mapcore-cli.exe lands in SDK\Bin\Dll, next to the runtime DLLs so they load, with
plugins.cfg and resources.cfg deployed beside it. The host sets its working directory to its
own folder so both resolve however it was launched.
Worth knowing
- The render system defaults to Direct3D 9 on Windows. Edit
plugins.cfg, or passrenderSystem=toDev-Create, to use D3D11 or OpenGL instead. - Zooming past a raster's finest level draws only the background colour. Nothing is broken —
there is simply no imagery at that scale. Raise
Vp-SetCameraScaleto back out. - Headless still renders.
Vp-RenderScreenRectToBufferuses the SDK's own off-screen path, so it works whether or not the window is visible. - Relative output paths resolve against the directory the client was launched from, not the host's.
Related
- Quickstart — the same sequence written as code.
- Samples — the full applications.
- MCP server — the same idea for an AI agent rather than a shell.