mapserver.github.io/mapcache/coverage.html at master · MapServer/mapserver.github.io

History

553 lines (507 loc) · 27.3 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

<!DOCTYPE html>

<head>

<title>Coverage Analyzer — MapServer 8.6.1 documentation</title>

</head><body>

<tr>

</td>

<a href="../index.html" title="Home">Home</a> |

<a href="../products.html" title="Products (MapServer core, MapCache, TinyOWS">Products</a> |

<a href="https://github.com/mapserver/mapserver/issues/" title="Issue Tracker (MapServer core)">Issue Tracker</a> |

<a href="../community/service_providers.html" title="Professional Service Providers">Service Providers</a> |

<a href="../faq.html" title="Frequently Asked Questions">FAQ</a> |

<a href="https://fosstodon.org/@mapserver" title="Mastodon" target="_blank">Mastodon</a> |

<a href="../download.html" title="Download Source or Binaries">Download </a> |

</a>

</td>

</tr>

<tr>

</td>

</tr>

</table>

<h3>Navigation</h3>

<ul>

<a href="../genindex.html" title="General Index"

accesskey="I">index</a></li>

<a href="../MIGRATION_GUIDE.html" title="MapServer Migration Guide"

accesskey="N">next</a> |</li>

<a href="locks.html" title="Locking Mechanisms"

accesskey="P">previous</a> |</li>

<li class="nav-item nav-item-1"><a href="../documentation.html" >MapServer 8.6.1 Documentation</a> »</li>

<li class="nav-item nav-item-2"><a href="index.html" accesskey="U">MapCache 1.14.1</a> »</li>

<li class="nav-item nav-item-this"><a href="">Coverage Analyzer</a></li>

</ul>

</div>

<span id="mapcache-detail"></span><h1>Coverage Analyzer<a class="headerlink" href="#coverage-analyzer" title="Link to this heading">¶</a></h1>

<dt class="field-odd">Author<span class="colon">:</span></dt>

<dd class="field-odd"><p>Jerome Boue</p>

</dd>

</dl>

<p><strong>mapcache_detail</strong> - Coverage analysis of MapCache SQLite Caches</p>

</section>

<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Link to this heading">¶</a></h2>

<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>mapcache_detail [ options ]

</pre></div>

</div>

</section>

<h2>DESCRIPTION<a class="headerlink" href="#description" title="Link to this heading">¶</a></h2>

<p><cite>mapcache_detail</cite> main use case is users wanting to use offline a portion of

a MapCache cache covering a given geographical region. For that purpose, they

need to identify relevant files from an existing cache, check whether tiles are

missing from these files (possibly seeding missing parts if necessary), and

extract these files to build a new cache of the requested region.</p>

<p><cite>mapcache_detail</cite>, helps users with some of these activities. It works with

SQLite caches where one single file may contains thousands of tiles. It

is able to:</p>

<li><p>Determine which SQLite files from the cache are needed to cover a given

geographical region at a given zoom level range;</p></li>

<li><p>Count how many tiles are needed to cover the region and how many are

already present in each file, giving a coverage ratio on file level, zoom

level and global level;</p></li>

<li><p>Estimate data size of missing tiles, which need to be downloaded to

entirely cover the requested region, again on file level, zoom level and

global level.</p></li>

</ul>

</div></blockquote>

<p><cite>mapcache_detail</cite> is able to handle all kinds of SQLite caches that MapCache

itself handles, namely:</p>

<li><p><a class="reference internal" href="caches.html#mapcache-cache-sqlite"><span class="std std-ref">Single SQLite caches</span></a>, where only one SQLite

database contains the whole cache;</p></li>

<li><p><a class="reference internal" href="caches.html#mapcache-cache-multisqlite"><span class="std std-ref">Multiple SQLite caches</span></a>, where cache is

split into multiple SQLite databases according to a given template;</p></li>

<li><p><a class="reference internal" href="caches.html#mapcache-cache-composite"><span class="std std-ref">Composite SQLite caches</span></a>, which are a

combination of single and multiple SQLite caches depending on zoom levels.</p></li>

</ul>

</div></blockquote>

<p><cite>mapcache_detail</cite> takes the form of an independent CLI executable using

MapCache library. It is proposed as a simple contribution to the MapCache

project under a <cite>contrib/mapcache_detail/</cite> folder, due to its specific

purpose (only SQLite caches are handled).</p>

</section>

<h2>OPTIONS<a class="headerlink" href="#options" title="Link to this heading">¶</a></h2>

<p>Some option have the same syntax and meaning as those of

<a class="reference internal" href="seed.html#mapcache-seed"><span class="std std-ref">mapcache_seeder utility</span></a>.</p>

<h3>Miscellaneous options<a class="headerlink" href="#miscellaneous-options" title="Link to this heading">¶</a></h3>

<dt><strong>-h, –help</strong></dt><dd><p>Display help message and exit.</p>

</dd>

<dt><strong>-o, –short-output</strong></dt><dd><p>(Optional) If this option is present, only Existing SQLite files are

reported, missing SQLite files are still taken into account for level and

global coverage.</p>

</dd>

</dl>

</section>

<h3>Options for specifying the cache to analyze<a class="headerlink" href="#options-for-specifying-the-cache-to-analyze" title="Link to this heading">¶</a></h3>

<dl>

<dt><strong>-c, –config</strong> <em>MapCache configuration file</em></dt><dd><p>(Required) Set MapCache configuration file in which cache to analyze is

specified.</p>

</dd>

<dt><strong>-t, –tileset</strong> <em>tileset name</em></dt><dd><p>(Required) Set the tileset to analyze.</p>

</dd>

<dt><strong>-g, –grid</strong> <em>grid name</em></dt><dd><p>(Required) Set the grid to analyze.</p>

</dd>

<dt><strong>-D, –dimension</strong> <em>DIMENSION_NAME=VALUE</em></dt><dd><p>(Optional) Set the value of a dimension. This option can be used multiple

times for multiple dimensions.</p>

</dd>

<dt><strong>-q, –query</strong> <value></dt><dd><p>(Optional) Set SQL query for counting tiles in a rectangle. Default value,

given below, works with default schema of SQLite caches.</p>

<div class="highlight-SQL notranslate"><div class="highlight"><pre><span></span><span class="k">SELECT</span><span class="w"> </span><span class="k">count</span><span class="p">(</span><span class="n">rowid</span><span class="p">)</span>

<span class="w"> </span><span class="k">FROM</span><span class="w"> </span><span class="n">tiles</span>

<span class="w"> </span><span class="k">WHERE</span><span class="w"> </span><span class="p">(</span><span class="n">x</span><span class="w"> </span><span class="k">between</span><span class="w"> </span><span class="p">:</span><span class="n">minx</span><span class="w"> </span><span class="k">and</span><span class="w"> </span><span class="p">:</span><span class="n">maxx</span><span class="p">)</span>

<span class="w"> </span><span class="k">AND</span><span class="w"> </span><span class="p">(</span><span class="n">y</span><span class="w"> </span><span class="k">between</span><span class="w"> </span><span class="p">:</span><span class="n">miny</span><span class="w"> </span><span class="k">and</span><span class="w"> </span><span class="p">:</span><span class="n">maxy</span><span class="p">)</span>

<span class="w"> </span><span class="k">AND</span><span class="w"> </span><span class="n">tileset</span><span class="o">=</span><span class="p">:</span><span class="n">tileset</span><span class="w"> </span><span class="k">AND</span><span class="w"> </span><span class="n">grid</span><span class="o">=</span><span class="p">:</span><span class="n">grid</span><span class="w"> </span><span class="k">AND</span><span class="w"> </span><span class="n">dim</span><span class="o">=</span><span class="p">:</span><span class="n">dim</span><span class="p">;</span>

</pre></div>

</div>

</dd>

</dl>

</section>

<h3>Options for specifying the region to cover<a class="headerlink" href="#options-for-specifying-the-region-to-cover" title="Link to this heading">¶</a></h3>

<dt><strong>-z, –zoom</strong> <em>minzoom[,maxzoom]</em></dt><dd><p>(Optional) Set min and max zoom levels to analyze, separated by a comma, eg:

12,15. If <em>maxzoom</em> is absent, only zoom level specified by <em>minzoom</em> is

analyzed. Default value is <em>0</em>.</p>

</dd>

</dl>

<h4>Rectangular region<a class="headerlink" href="#rectangular-region" title="Link to this heading">¶</a></h4>

<dt><strong>-e, –extent</strong> <em>minx,miny,maxx,maxy</em></dt><dd><p>(Optional) Set the extent to analyze. Default value is the whole grid

extent. This option cannot be used with <strong>–ogr-datasource</strong> option.</p>

</dd>

</dl>

</section>

<h4>Polygonal region<a class="headerlink" href="#polygonal-region" title="Link to this heading">¶</a></h4>

<dt><strong>-d, –ogr-datasource</strong> <em>OGR data source</em></dt><dd><p>(Optional) Set the OGR data source to get features from. Any <a class="reference external" href="https://gdal.org/drivers/vector/index.html">OGR Vector

Format</a> can be used. If absent, the region is specified using <strong>–extent</strong>

option, possibly its default value. This option cannot be used with

<strong>–extent</strong> option.</p>

</dd>

<dt><strong>-l, –ogr-layer</strong> <em>layer</em></dt><dd><p>(Optional) Select the layer inside OGR data source. This option works only

if <strong>–ogr-datasource</strong> has been specified. This option cannot be used with

<strong>–ogr-sql</strong> option.</p>

</dd>

<dt><strong>-w, –ogr-where</strong> <em>filter</em></dt><dd><p>(Optional) Set a filter to apply on OGR layer features. This option works

only if <strong>–ogr-datasource</strong> has been specified. This option cannot be used

with <strong>–ogr-sql</strong> option.</p>

</dd>

<dt><strong>-s, –ogr-sql</strong> <em>SQL query</em></dt><dd><p>(Optional) SQL query to filter inside OGR data source. This option works

only if <strong>–ogr-datasource</strong> has been specified. This option cannot be used

with –ogr-layer or –ogr-where.</p>

</dd>

</dl>

</section>

<h2>COUNTING TILES<a class="headerlink" href="#counting-tiles" title="Link to this heading">¶</a></h2>

<p>To illustrate the process, here is an example of a fictional grid. Tiles are

represented by the smallest squares on the grid. Larger squares of 25 tiles

each represent SQLite files. Small indices denote tile coordinates whereas

large indices denote databases coordinates. Colored rectangle represents

requested region for cache extraction. Darker tiles represent tiles present in

cache.</p>

<p>Expressed in tiles, region coordinates <em>(xmin, ymin, xmax, ymax)</em> are

(11, 7, 27, 20). Expressed in SQLite files, these coordinates are (2, 1, 5, 4).

All files whose coordinates are comprised between (2, 1) and (5, 4) included

shall be part of the cache extraction. All tiles whose coordinates are

comprised between (11, 7) and (27, 20) included shall be counted for the region

coverage.</p>

<p>Following table gives tile count and coverage ratio of requested region,

according to tool’s process:</p>

<thead>

<tr class="row-odd"><th class="head"><p>SQlite file</p></th>

<th class="head"><p>Total</p></th>

</tr>

</thead>

<tbody>

<tr class="row-even"><td><p>Tiles present

in cache and

covering

region</p></td>

</tr>

<tr class="row-odd"><td><p>Tiles needed

to fully

cover region</p></td>

</tr>

<tr class="row-even"><td><p>Coverage</p></td>

</tr>

</tbody>

</table>

</section>

<h2>OUTPUT REPORT<a class="headerlink" href="#output-report" title="Link to this heading">¶</a></h2>

<p>Tool’s output, in JSON format, provides user with SQLite file list to be

extracted from cache. Details are given on the number of tiles contributing to

region coverage. A synthesis is also given for each zoom level and at a global

level.</p>

<p>Following is a fictional example describing information present in tool’s

output.</p>

<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>{ _______________________________________

"layer": "example", | Report starts with general information

"grid": "local", | on cache and requested region

"unit": "m",

"region": {

"bounding_box": [ 11, 7, 27, 20 ],

"geometry": {

"type": "Polygon",

"coordinates": [[ [11,7], [11,20], [27,20], [27,7], [11,7] ]]

}

"zoom-levels": [ {

"level": 1,

"files": [ { _______________________________________

| For each file, output report gives:

| its name, its size, its bounding box

| and intersection of that bounding box

| with requested region

"file_name": "/path/to/cache/example/1/2-1.sqlite",

"file_size": 54632,

"file_bounding_box": [ 10, 5, 14, 9 ],

"region_in_file": {

"bounding_box": [ 11, 7, 14, 9 ],

"geometry": {

"type": "Polygon",

"coordinates":

[[ [11,7], [11,9], [14,9], [14,7], [11,7] ]]

}

"nb_tiles_in_region": { ___________________________________

| Measures associated to a SQLite file

| are: number of tiles belonging to

| requested region and present in file,

| number of tiles belonging to region

| present or not in file, and resulting

| coverage ratio

"cached_in_file": 0,

"max_in_file": 12,

"coverage": 0

}

}, {

"file_name": ...

...

} ],

"nb_tiles_in_region": { _______________________________________

| Measures associated to a zoom level

| are the sum of the ones for each SQLite

| file of that level

"cached_in_level": 43,

"max_in_level": 238,

"coverage": 0.1807

}

}, {

"level": 2,

...

} ],

"nb_tiles_in_region": { _______________________________________

"cached_in_cache": 43, | Global measures are the sum of all

"max_in_cache": 238, | zoom level measures

"coverage": 0.1807

"sizes": { _______________________________________

| At global level estimations about

| cache size to be extracted for a full

| region coverage are also given. These

| estimations are based on the mean size

| of a tile obtained from all SQLite file

| sizes and how many tiles they contain

"total_size_of_files": 1599442,

"total_nb_tiles_in_files": 60,

"average_tile_size": 26658,

"estimated_max_cache_size": 6344604,

"estimated_cached_cache_size": 1146294,

"estimated_missing_cache_size": 5198310

}

</pre></div>

</div>

</section>

<h2>EXAMPLES<a class="headerlink" href="#examples" title="Link to this heading">¶</a></h2>

<p>Analyze tile coverage of tileset <em>osm</em> with the <em>g</em> grid. Default extent is the

whole world and default zoom level is 0:</p>

<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>mapcache_detail --config mapcache.xml --tileset osm --grid g

</pre></div>

</div>

<p>Same as beforehand, with explicit zoom levels 9 to 12 and explicit extent

covering Switzerland:</p>

<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>mapcache_detail --config mapcache.xml --tileset osm --grid g --zoom 9,12 --extent 663000,5751230,1167680,6075050

</pre></div>

</div>

</section>

</div>

<h3 id="searchlabel">Quick search</h3>

</form>

</div>

</search>

<p>

<a href="../about.html" title="About">About</a><br>

<a href="../products.html" title="Products">Products</a><br>

<a href="../community/index.html" title="Community">Community</a><br>

<a href="../development/index.html" title="Development">Development</a><br>

<a href="../download.html" title="Downloads">Downloads</a><br>

<a href="../documentation.html" title="Documentation">Documentation</a><br>

<a href="https://fosstodon.org/@mapserver" title="Mastodon">Mastodon</a>

</p>

<h3>Current Table Of Contents</h3>

<ul>

<li><a class="reference internal" href="#">Coverage Analyzer</a><ul>

<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li>

<li><a class="reference internal" href="#description">DESCRIPTION</a></li>

<li><a class="reference internal" href="#options">OPTIONS</a><ul>

<li><a class="reference internal" href="#miscellaneous-options">Miscellaneous options</a></li>

<li><a class="reference internal" href="#options-for-specifying-the-cache-to-analyze">Options for specifying the cache to analyze</a></li>

<li><a class="reference internal" href="#options-for-specifying-the-region-to-cover">Options for specifying the region to cover</a><ul>

<li><a class="reference internal" href="#rectangular-region">Rectangular region</a></li>

<li><a class="reference internal" href="#polygonal-region">Polygonal region</a></li>

</ul>

</li>

</ul>

</li>

<li><a class="reference internal" href="#counting-tiles">COUNTING TILES</a></li>

<li><a class="reference internal" href="#output-report">OUTPUT REPORT</a></li>

<li><a class="reference internal" href="#examples">EXAMPLES</a></li>

</ul>

</li>

</ul>

</div>

</div>

<h3>Navigation</h3>

<ul>

<a href="../genindex.html" title="General Index"

>index</a></li>

<a href="../MIGRATION_GUIDE.html" title="MapServer Migration Guide"

>next</a> |</li>

<a href="locks.html" title="Locking Mechanisms"

>previous</a> |</li>

<li class="nav-item nav-item-1"><a href="../documentation.html" >MapServer 8.6.1 Documentation</a> »</li>

<li class="nav-item nav-item-2"><a href="index.html" >MapCache 1.14.1</a> »</li>

<li class="nav-item nav-item-this"><a href="">Coverage Analyzer</a></li>

</ul>

</div>

Last updated on 2026-03-30.

Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 9.1.0.

</div>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

coverage.html

Latest commit

History

coverage.html

File metadata and controls