Skip to main content
info

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

Preview

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 flagDefault
--port <p>5000
--width <w>1024
--height <h>768
--showhidden (headless)
--log <file> or --log nonemapcore-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:

PrefixInterface
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.

CommandCalls
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, helpThe 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 pass renderSystem= to Dev-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-SetCameraScale to back out.
  • Headless still renders. Vp-RenderScreenRectToBuffer uses 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.
  • Quickstart — the same sequence written as code.
  • Samples — the full applications.
  • MCP server — the same idea for an AI agent rather than a shell.

Written from Map/IMcMapDevice.h, Map/IMcMapViewport.h, Map/IMcMapTerrain.h, Map/IMcRasterMapLayer.h