Merge pull request #60 from yuiseki/main

Release 2026-01-14 07:10:34 UTC

Author: yuiseki

AGENTS.md

@@ -13,5 +13,6 @@
 - When editing PR bodies, do not paste raw `cargo test --verbose` output. If you ran `make test` and it passed, just check the Testing checkbox.
 - Do not use `gh pr edit` to update PR bodies. Use `gh api -X PATCH` instead.
 - Avoid `gh pr create`. Create PRs with `gh api -X POST /repos/<owner>/<repo>/pulls` and pass `title`, `head`, `base`, and `body`.
+- Always update `CHANGELOG.md` for user-visible changes before releasing.
 - When asked to bump versions, follow `docs/RELEASE.md`.
 - Release flow: `main` → `release` PRs are auto-created/updated; tags are created by workflow on `release` merges and releases are dispatched automatically.

CHANGELOG.md

@@ -20,6 +20,16 @@ The format is based on Keep a Changelog and adheres to Semantic Versioning.
 ### Security
 - TBD_UNVT_CHANGELOG_SECURITY
 
+## [0.4.3] - 2026-01-14
+### Added
+- Add a "Top 10 big tiles" section to inspect text output (respects --zoom).
+- Allow `inspect -z/-x/-y` to show tile summaries in compat-style arguments.
+- Document an inspect workflow and tips in HOW_TO.
+
+### Changed
+- Hide Metadata/Summary/Histogram/Layers output when `-x/-y` are provided.
+- Skip "Top 10 big tiles" output when `-x/-y` are provided.
+
 ## [0.4.2] - 2026-01-14
 ### Changed
 - Improve inspect text output readability (summary list items, zoom table with percentages).

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "vt-optimizer-rs"
-version = "0.4.2"
+version = "0.4.3"
 edition = "2024"
 license = "MIT"
 description = "A fast CLI to inspect and optimize MBTiles/PMTiles vector tiles."

Cargo.toml

@@ -25,6 +25,38 @@ Notes:
 - `--fast` uses sampling to reduce runtime and output volume.
 - For machine-readable output, add `--output ndjson`.
 
+### Inspect workflow and tips
+
+1) Start with full inspect output to identify the heaviest zoom level:
+
+```bash
+cargo run -- inspect "$MBTILES_PATH"
+```
+
+- The `## Zoom` section shows total size by zoom. Pick the zoom level with the
+  largest total size or max tile size for deeper inspection.
+
+2) Drill into a zoom level and list the largest tiles:
+
+```bash
+cargo run -- inspect "$MBTILES_PATH" --zoom 5
+```
+
+- The `## Top 10 big tiles` section prints copy-pasteable arguments like
+  `-z 5 -x 16 -y 20`, so you can inspect those tiles directly.
+
+3) Inspect a specific tile to see which layers and properties dominate:
+
+```bash
+cargo run -- inspect "$MBTILES_PATH" --zoom 5 -x 16 -y 20
+```
+
+Tips:
+- When `-x/-y` are provided, output focuses on `## Tile Summary` for that tile.
+- If you need a smaller report, use `--stats` to select sections or `--fast`
+  to sample.
+- Use `--output ndjson` when you want to script or diff results.
+
 ## Optimize
 
 If the output file already exists, remove it first:

docs/HOW_TO.md

@@ -33,6 +33,10 @@ Optional: create a local release branch name to mirror the target version:
 VERSION=0.2.0 BUMP_BRANCH=1 make bump-version
 ```
 
+## Changelog updates
+
+- Always update `CHANGELOG.md` with user-visible changes before release.
+
 ## Notes
 
 - Only maintainers should merge into `release`.

docs/RELEASE.md

@@ -556,6 +556,11 @@ v0.0.4 では以下を **含めない**。
 * `inspect` の text 出力で Zoom セクションをテーブル表示に変更（%tiles/%size/acc% 追加）
 * `inspect` の text 出力から Histogram by Zoom セクションを除外し、Histogram に注意書きを追加
 
+## 1.66 マイルストーン（v0.4.3）
+
+* `inspect` の text 出力に Top 10 big tiles セクションを追加
+* `inspect` で `-z/-x/-y` 指定時に Tile Summary を表示
+
 ## 2. 用語
 
 * **Tile key**: `z/x/y`（内部表現は XYZ）

docs/SPEC.md

@@ -92,9 +92,17 @@ pub struct InspectArgs {
     pub no_progress: bool,
 
     /// Limit inspection to a specific zoom level.
-    #[arg(long)]
+    #[arg(long, short = 'z')]
     pub zoom: Option<u8>,
 
+    /// Tile x (use with -z/--zoom and -y to show tile summary).
+    #[arg(short = 'x')]
+    pub x: Option<u32>,
+
+    /// Tile y (use with -z/--zoom and -x to show tile summary).
+    #[arg(short = 'y')]
+    pub y: Option<u32>,
+
     /// Histogram bucket index (0-based) used with --list-tiles.
     #[arg(long)]
     pub bucket: Option<usize>,

src/cli.rs

@@ -13,8 +13,8 @@ use vt_optimizer::mbtiles::{
 };
 use vt_optimizer::output::{
     format_bytes, format_histogram_table, format_histograms_by_zoom_section,
-    format_metadata_section, format_zoom_table, ndjson_lines, pad_left, pad_right,
-    resolve_output_format,
+    format_metadata_section, format_top_tiles_lines, format_zoom_table, ndjson_lines, pad_left,
+    pad_right, resolve_output_format,
 };
 use vt_optimizer::pmtiles::{
     inspect_pmtiles_with_options, mbtiles_to_pmtiles, pmtiles_to_mbtiles, prune_pmtiles_layer_only,
@@ -220,6 +220,8 @@ fn main() -> Result<()> {
                     stats: Some("tile_summary".to_string()),
                     no_progress: false,
                     zoom: None,
+                    x: None,
+                    y: None,
                     bucket: None,
                     tile: Some(format!("{}/{}/{}", z, x, y)),
                     summary: true,
@@ -247,6 +249,8 @@ fn main() -> Result<()> {
                 stats: None,
                 no_progress: false,
                 zoom: None,
+                x: None,
+                y: None,
                 bucket: None,
                 tile: None,
                 summary: false,
@@ -284,14 +288,25 @@ fn run_inspect(args: vt_optimizer::cli::InspectArgs) -> Result<()> {
         Some(value) => Some(parse_sample_spec(value)?),
         None => None,
     };
-    let tile = match args.tile.as_deref() {
+    let mut tile = match args.tile.as_deref() {
         Some(value) => Some(parse_tile_spec(value)?),
         None => None,
     };
-    if args.summary && tile.is_none() {
+    if tile.is_some() && (args.x.is_some() || args.y.is_some()) {
+        anyhow::bail!("--tile cannot be combined with -x/-y");
+    }
+    if tile.is_none() {
+        if let (Some(z), Some(x), Some(y)) = (args.zoom, args.x, args.y) {
+            tile = Some(vt_optimizer::mbtiles::TileCoord { zoom: z, x, y });
+        } else if args.x.is_some() || args.y.is_some() {
+            anyhow::bail!("-x/-y require -z/--zoom");
+        }
+    }
+    let summary = args.summary || (tile.is_some() && args.tile.is_none() && args.x.is_some());
+    if summary && tile.is_none() {
         anyhow::bail!("--summary requires --tile z/x/y");
     }
-    if tile.is_some() && !args.summary {
+    if tile.is_some() && !summary {
         anyhow::bail!("--tile requires --summary");
     }
     let mut layers = args.layers.clone();
@@ -307,7 +322,7 @@ fn run_inspect(args: vt_optimizer::cli::InspectArgs) -> Result<()> {
     } else {
         args.topn
     };
-    let (sample, topn, histogram_buckets) = if args.fast {
+    let (sample, mut topn, histogram_buckets) = if args.fast {
         (
             Some(vt_optimizer::mbtiles::SampleSpec::Ratio(0.1)),
             Some(5),
@@ -316,16 +331,20 @@ fn run_inspect(args: vt_optimizer::cli::InspectArgs) -> Result<()> {
     } else {
         (sample, topn, args.histogram_buckets as usize)
     };
+    if output == ReportFormat::Text && topn.unwrap_or(0) == 0 {
+        topn = Some(10);
+    }
+    let topn_value = topn.unwrap_or(0) as usize;
     let options = InspectOptions {
         sample,
-        topn: topn.unwrap_or(0) as usize,
+        topn: topn_value,
         histogram_buckets,
         no_progress: args.no_progress,
         max_tile_bytes: args.max_tile_bytes,
         zoom: args.zoom,
         bucket: args.bucket,
         tile,
-        summary: args.summary,
+        summary,
         layers,
         recommend: args.recommend,
         include_layer_list: output == ReportFormat::Text
@@ -390,26 +409,28 @@ fn run_inspect(args: vt_optimizer::cli::InspectArgs) -> Result<()> {
             let include_histogram_by_zoom = args.stats.is_some()
                 && stats_filter.includes(vt_optimizer::output::StatsSection::HistogramByZoom);
             let include_layers = stats_filter.includes(vt_optimizer::output::StatsSection::Layers);
+            let hide_tile_summary_sections = args.x.is_some() && args.y.is_some();
             let include_recommendations =
                 stats_filter.includes(vt_optimizer::output::StatsSection::Recommendations);
             let include_bucket = stats_filter.includes(vt_optimizer::output::StatsSection::Bucket);
             let include_bucket_tiles =
                 stats_filter.includes(vt_optimizer::output::StatsSection::BucketTiles);
-            let include_top_tiles =
-                stats_filter.includes(vt_optimizer::output::StatsSection::TopTiles);
+            let include_top_tiles = stats_filter
+                .includes(vt_optimizer::output::StatsSection::TopTiles)
+                && !hide_tile_summary_sections;
             let include_top_tile_summaries =
                 stats_filter.includes(vt_optimizer::output::StatsSection::TopTileSummaries);
             let include_tile_summary =
                 stats_filter.includes(vt_optimizer::output::StatsSection::TileSummary);
             println!("{}", format_inspect_title(&args.input));
             println!();
-            if include_metadata && !report.metadata.is_empty() {
+            if include_metadata && !hide_tile_summary_sections && !report.metadata.is_empty() {
                 for line in format_metadata_section(&report.metadata) {
                     println!("{}", emphasize_section_heading(&line));
                 }
                 println!();
             }
-            if include_summary {
+            if include_summary && !hide_tile_summary_sections {
                 println!("{}", emphasize_section_heading("## Summary"));
                 println!(
                     "{}",
@@ -490,21 +511,24 @@ fn run_inspect(args: vt_optimizer::cli::InspectArgs) -> Result<()> {
                     );
                 }
             }
-            if include_histogram && !report.histogram.is_empty() {
+            if include_histogram && !hide_tile_summary_sections && !report.histogram.is_empty() {
                 println!();
                 println!("{}", emphasize_section_heading("## Histogram"));
                 for line in format_histogram_table(&report.histogram) {
                     println!("{}", emphasize_table_header(&line));
                 }
             }
-            if include_histogram_by_zoom && !report.histograms_by_zoom.is_empty() {
+            if include_histogram_by_zoom
+                && !hide_tile_summary_sections
+                && !report.histograms_by_zoom.is_empty()
+            {
                 println!();
                 for line in format_histograms_by_zoom_section(&report.histograms_by_zoom) {
                     let line = emphasize_section_heading(&line);
                     println!("{}", emphasize_table_header(&line));
                 }
             }
-            if include_layers && !report.file_layers.is_empty() {
+            if include_layers && !hide_tile_summary_sections && !report.file_layers.is_empty() {
                 println!();
                 println!("{}", emphasize_section_heading("## Layers"));
                 let name_width = report
@@ -600,12 +624,12 @@ fn run_inspect(args: vt_optimizer::cli::InspectArgs) -> Result<()> {
             }
             if include_top_tiles && !report.top_tiles.is_empty() {
                 println!();
-                println!("{}", emphasize_section_heading("## Top Tiles"));
-                for tile in report.top_tiles.iter() {
-                    println!(
-                        "- z={}: x={} y={} bytes={}",
-                        tile.zoom, tile.x, tile.y, tile.bytes
-                    );
+                println!(
+                    "{}",
+                    emphasize_section_heading(&format!("## Top {} big tiles", topn_value))
+                );
+                for line in format_top_tiles_lines(&report.top_tiles) {
+                    println!("{}", line);
                 }
             }
             if include_top_tile_summaries && !report.top_tile_summaries.is_empty() {

src/main.rs

@@ -6,7 +6,8 @@ use crate::cli::{ReportFormat, TileInfoFormat};
 use std::collections::BTreeMap;
 
 use crate::mbtiles::{
-    FileLayerSummary, HistogramBucket, MbtilesReport, MbtilesZoomStats, TileSummary, ZoomHistogram,
+    FileLayerSummary, HistogramBucket, MbtilesReport, MbtilesZoomStats, TileSummary, TopTile,
+    ZoomHistogram,
 };
 
 use std::collections::BTreeSet;
@@ -478,6 +479,21 @@ pub fn format_zoom_table(
     lines
 }
 
+pub fn format_top_tiles_lines(tiles: &[TopTile]) -> Vec<String> {
+    tiles
+        .iter()
+        .map(|tile| {
+            format!(
+                "-z {} -x {} -y {} size={}",
+                tile.zoom,
+                tile.x,
+                tile.y,
+                format_bytes(tile.bytes)
+            )
+        })
+        .collect()
+}
+
 pub fn format_tile_summary_text(summary: &TileSummary) -> Vec<String> {
     let label = |text: &str| Color::Blue.paint(text).to_string();
     vec![