pi-revit 0.4.0 → 0.5.0

package/src/Revit/Tools/ManageSheetPlacements.cs

@@ -1,97 +1,113 @@
-using System.Text.Json;
-using Autodesk.Revit.DB;
-
-namespace RevitBridge.Tools;
-
-internal sealed class ManageSheetPlacements : ITool
-{
-    public string Name => "manage_sheet_placements";
-    public string Label => "Manage Sheet Placements";
-    public string Tier => "advanced";
-    public bool Write => true;
-    public string Description => "List, place or move viewports and schedule instances on a sheet. Positions are paper-space sheet coordinates with explicit length units, [x,y,0]; never multiply by view scale. For viewports position is the box center excluding its label; for schedules it is the insertion point. Place requires sheet_id/view_id, move requires placement_id. Viewports may rotate none/clockwise/counterclockwise; schedule rotation is not supported. preview=true commit-validates then rolls back; new placement IDs are temporary. List includes both viewports and schedules with paging. Exact document identity is required for every action.";
-    public object ParametersSchema => new
-    {
-        type = "object", properties = new
-        {
-            action = new { type = "string", @enum = new[] { "list", "place", "move" } },
-            sheet_id = new { type = "integer", minimum = 1 }, view_id = new { type = "integer", minimum = 1 }, placement_id = new { type = "integer", minimum = 1 },
-            position = ModelEditInputs.VectorSchema("Sheet paper-space [x,y,0] in unit."), unit = ModelEditInputs.LengthUnitSchema,
-            rotation = new { type = "string", @enum = new[] { "none", "clockwise", "counterclockwise" } },
-            offset = new { type = "integer", minimum = 0 }, limit = new { type = "integer", minimum = 1, maximum = 200 }, preview = ModelEditInputs.PreviewSchema,
-        }, required = new[] { "action" },
-    };
-    public object Execute(JsonElement args, ToolContext context)
-    {
-        var doc = context.Document ?? throw new NoActiveDocumentException();
-        string action = JsonArgs.GetString(args, "action") ?? "";
-        ElementId Id(string name) => new(JsonArgs.GetLong(args, name) is long id && id > 0 ? id : throw new ArgumentException($"{name} must be a positive ID."));
-        if (action == "list")
-        {
-            var sheet = doc.GetElement(Id("sheet_id")) as ViewSheet ?? throw new ArgumentException("sheet_id is not a sheet.");
-            var items = new FilteredElementCollector(doc).OwnedByView(sheet.Id).WhereElementIsNotElementType()
-                .Where(e => e is Viewport or ScheduleSheetInstance).OrderBy(e => e.Id.Value).ToArray();
-            int offset = JsonArgs.GetInt(args, "offset", 0), limit = JsonArgs.GetInt(args, "limit", 100);
-            if (offset < 0 || limit is < 1 or > 200) throw new ArgumentException("Invalid paging range.");
-            var page = items.Skip(offset).Take(limit).Select(Describe).ToArray();
-            return new { sheet_id = sheet.Id.Value, total_count = items.Length, offset, returned_count = page.Length, next_offset = offset + page.Length < items.Length ? (int?)(offset + page.Length) : null, placements = page, coordinate_system = "sheet_paper", unit = "feet" };
-        }
-        if (action is not ("place" or "move")) throw new ArgumentException("action must be list, place or move.");
-        var point = ModelEditInputs.Vector(args, "position").Multiply(ModelEditInputs.LengthScale(args));
-        if (Math.Abs(point.Z) > 1e-9) throw new ArgumentException("Sheet position Z must be zero.");
-        var rotation = JsonArgs.GetString(args, "rotation") switch
-        {
-            null => (ViewportRotation?)null, "none" => ViewportRotation.None, "clockwise" => ViewportRotation.Clockwise,
-            "counterclockwise" => ViewportRotation.Counterclockwise, _ => throw new ArgumentException("Invalid rotation."),
-        };
-        return ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(new() { ["action"] = action }, () =>
-        {
-            Element placement;
-            object? before = null;
-            if (action == "place")
-            {
-                var sheet = doc.GetElement(Id("sheet_id")) as ViewSheet ?? throw new ArgumentException("sheet_id is not a sheet.");
-                if (sheet.IsPlaceholder) throw new ArgumentException("Cannot place content on a placeholder sheet.");
-                var view = doc.GetElement(Id("view_id")) as View ?? throw new ArgumentException("view_id is not a view or schedule.");
-                if (view is ViewSchedule schedule)
-                {
-                    if (rotation != null) throw new ArgumentException("Schedules do not support viewport rotation.");
-                    placement = ScheduleSheetInstance.Create(doc, sheet.Id, schedule.Id, point);
-                }
-                else
-                {
-                    if (!Viewport.CanAddViewToSheet(doc, sheet.Id, view.Id)) throw new ArgumentException("This view cannot be added to that sheet; it may already be placed.");
-                    placement = Viewport.Create(doc, sheet.Id, view.Id, point);
-                }
-            }
-            else
-            {
-                placement = doc.GetElement(Id("placement_id")) ?? throw new ArgumentException("placement_id was not found.");
-                if (args.TryGetProperty("sheet_id", out _) && placement.OwnerViewId != Id("sheet_id")) throw new ArgumentException("The placement does not belong to the expected sheet_id.");
-                if (placement.Pinned) throw new ArgumentException("Placement is pinned; it was not unpinned.");
-                before = Describe(placement);
-                if (placement is Viewport viewport) viewport.SetBoxCenter(point);
-                else if (placement is ScheduleSheetInstance schedule)
-                {
-                    if (rotation != null) throw new ArgumentException("Schedules do not support viewport rotation.");
-                    schedule.Point = point;
-                }
-                else throw new ArgumentException("placement_id must identify a viewport or schedule instance.");
-            }
-            if (rotation != null && placement is Viewport target) target.Rotation = rotation.Value;
-            doc.Regenerate();
-            if (placement is Viewport positioned) { positioned.SetBoxCenter(point); doc.Regenerate(); }
-            return new() { ["before"] = before, ["placement"] = Describe(placement), ["created"] = action == "place", ["id_is_temporary"] = action == "place" && JsonArgs.GetBool(args, "preview", false) };
-        }) }).Payload;
-    }
-    private static object Describe(Element element)
-    {
-        static double[] Point(XYZ p) => new[] { p.X, p.Y, p.Z };
-        return element switch
-        {
-            Viewport v => new { id = v.Id.Value, unique_id = v.UniqueId, kind = "viewport", sheet_id = v.SheetId.Value, view_id = v.ViewId.Value, position = Point(v.GetBoxCenter()), position_kind = "box_center_excluding_label", rotation = v.Rotation.ToString(), unit = "feet" } as object,
-            ScheduleSheetInstance s => new { id = s.Id.Value, unique_id = s.UniqueId, kind = "schedule", sheet_id = s.OwnerViewId.Value, view_id = s.ScheduleId.Value, position = Point(s.Point), position_kind = "insertion_point", unit = "feet" },
-            _ => throw new ArgumentException("Element is not a sheet placement."),
-        };
-    }
-}
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class ManageSheetPlacements : ITool
+{
+    public string Name => "manage_sheet_placements";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.ProjectOnly;
+    public IReadOnlyList<string> Keywords => new[] { "viewport", "place view on sheet", "sheet layout", "move viewport", "schedule on sheet", "arrange sheet" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Creating the source view or schedule", "tool", "manage_views; manage_schedules"),
+        new ToolLimit("Rotating schedule instances", "api", "ScheduleSheetInstance.Rotation"),
+        new ToolLimit("Changing the titleblock", "tool", "change_element_types on the titleblock instance"),
+    };
+    public string? Verification => "capture";
+    public string Label => "Manage Sheet Placements";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "List, place or move viewports and schedule instances on a sheet. Positions are paper-space sheet coordinates with explicit length units, [x,y,0]; never multiply by view scale. For viewports position is the box center excluding its label; for schedules it is the insertion point. Place requires sheet_id/view_id, move requires placement_id. Viewports may rotate none/clockwise/counterclockwise; schedule rotation is not supported. preview=true commit-validates then rolls back; new placement IDs are temporary. List includes viewports, schedules and the titleblock's own revision schedules (kind titleblock_revision_schedule: part of the titleblock, not placed content), with paging and per-kind counts over the whole sheet. Exact document identity is required for every action.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            action = new { type = "string", @enum = new[] { "list", "place", "move" } },
+            sheet_id = new { type = "integer", minimum = 1 }, view_id = new { type = "integer", minimum = 1 }, placement_id = new { type = "integer", minimum = 1 },
+            position = ModelEditInputs.VectorSchema("Sheet paper-space [x,y,0] in unit."), unit = ModelEditInputs.LengthUnitSchema,
+            rotation = new { type = "string", @enum = new[] { "none", "clockwise", "counterclockwise" } },
+            offset = new { type = "integer", minimum = 0 }, limit = new { type = "integer", minimum = 1, maximum = 200 }, preview = ModelEditInputs.PreviewSchema,
+        }, required = new[] { "action" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        string action = JsonArgs.GetString(args, "action") ?? "";
+        ElementId Id(string name) => new(JsonArgs.GetLong(args, name) is long id && id > 0 ? id : throw new ArgumentException($"{name} must be a positive ID."));
+        if (action == "list")
+        {
+            var sheet = doc.GetElement(Id("sheet_id")) as ViewSheet ?? throw new ArgumentException("sheet_id is not a sheet.");
+            var items = new FilteredElementCollector(doc).OwnedByView(sheet.Id).WhereElementIsNotElementType()
+                .Where(e => e is Viewport or ScheduleSheetInstance).OrderBy(e => e.Id.Value).ToArray();
+            int offset = JsonArgs.GetInt(args, "offset", 0), limit = JsonArgs.GetInt(args, "limit", 100);
+            if (offset < 0 || limit is < 1 or > 200) throw new ArgumentException("Invalid paging range.");
+            var page = items.Skip(offset).Take(limit).Select(Describe).ToArray();
+            // Counts cover the whole sheet, so "is anything placed?" never depends on paging
+            // or on mistaking the titleblock's revision schedule for placed content.
+            var kinds = items.Select(ElementTraits.PlacementKind).ToArray();
+            var counts = new { viewports = kinds.Count(k => k == "viewport"), schedules = kinds.Count(k => k == "schedule"),
+                titleblock_revision_schedules = kinds.Count(k => k == "titleblock_revision_schedule") };
+            return new { sheet_id = sheet.Id.Value, total_count = items.Length, counts, offset, returned_count = page.Length, next_offset = offset + page.Length < items.Length ? (int?)(offset + page.Length) : null, placements = page, coordinate_system = "sheet_paper", unit = "feet" };
+        }
+        if (action is not ("place" or "move")) throw new ArgumentException("action must be list, place or move.");
+        var point = ModelEditInputs.Vector(args, "position").Multiply(ModelEditInputs.LengthScale(args));
+        if (Math.Abs(point.Z) > 1e-9) throw new ArgumentException("Sheet position Z must be zero.");
+        var rotation = JsonArgs.GetString(args, "rotation") switch
+        {
+            null => (ViewportRotation?)null, "none" => ViewportRotation.None, "clockwise" => ViewportRotation.Clockwise,
+            "counterclockwise" => ViewportRotation.Counterclockwise, _ => throw new ArgumentException("Invalid rotation."),
+        };
+        return ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(new() { ["action"] = action }, () =>
+        {
+            Element placement;
+            object? before = null;
+            if (action == "place")
+            {
+                var sheet = doc.GetElement(Id("sheet_id")) as ViewSheet ?? throw new ArgumentException("sheet_id is not a sheet.");
+                if (sheet.IsPlaceholder) throw new ArgumentException("Cannot place content on a placeholder sheet.");
+                var view = doc.GetElement(Id("view_id")) as View ?? throw new ArgumentException("view_id is not a view or schedule.");
+                if (view is ViewSchedule schedule)
+                {
+                    if (rotation != null) throw new ArgumentException("Schedules do not support viewport rotation.");
+                    placement = ScheduleSheetInstance.Create(doc, sheet.Id, schedule.Id, point);
+                }
+                else
+                {
+                    if (!Viewport.CanAddViewToSheet(doc, sheet.Id, view.Id)) throw new ArgumentException("This view cannot be added to that sheet; it may already be placed.");
+                    placement = Viewport.Create(doc, sheet.Id, view.Id, point);
+                }
+            }
+            else
+            {
+                placement = doc.GetElement(Id("placement_id")) ?? throw new ArgumentException("placement_id was not found.");
+                if (args.TryGetProperty("sheet_id", out _) && placement.OwnerViewId != Id("sheet_id")) throw new ArgumentException("The placement does not belong to the expected sheet_id.");
+                if (placement.Pinned) throw new ArgumentException("Placement is pinned; it was not unpinned.");
+                if (ElementTraits.PlacementKind(placement) == "titleblock_revision_schedule")
+                    throw new ArgumentException("This is the titleblock's revision schedule; it belongs to the titleblock family and is not moved as a placement.");
+                before = Describe(placement);
+                if (placement is Viewport viewport) viewport.SetBoxCenter(point);
+                else if (placement is ScheduleSheetInstance schedule)
+                {
+                    if (rotation != null) throw new ArgumentException("Schedules do not support viewport rotation.");
+                    schedule.Point = point;
+                }
+                else throw new ArgumentException("placement_id must identify a viewport or schedule instance.");
+            }
+            if (rotation != null && placement is Viewport target) target.Rotation = rotation.Value;
+            doc.Regenerate();
+            if (placement is Viewport positioned) { positioned.SetBoxCenter(point); doc.Regenerate(); }
+            return new() { ["before"] = before, ["placement"] = Describe(placement), ["created"] = action == "place", ["id_is_temporary"] = action == "place" && JsonArgs.GetBool(args, "preview", false) };
+        }) }).Payload;
+    }
+    private static object Describe(Element element)
+    {
+        static double[] Point(XYZ p) => new[] { p.X, p.Y, p.Z };
+        return element switch
+        {
+            Viewport v => new { id = v.Id.Value, unique_id = v.UniqueId, kind = ElementTraits.PlacementKind(v), sheet_id = v.SheetId.Value, view_id = v.ViewId.Value, position = Point(v.GetBoxCenter()), position_kind = "box_center_excluding_label", rotation = v.Rotation.ToString(), unit = "feet", traits = ElementTraits.For(v) } as object,
+            ScheduleSheetInstance s => new { id = s.Id.Value, unique_id = s.UniqueId, kind = ElementTraits.PlacementKind(s), sheet_id = s.OwnerViewId.Value, view_id = s.ScheduleId.Value, position = Point(s.Point), position_kind = "insertion_point", unit = "feet", traits = ElementTraits.For(s) },
+            _ => throw new ArgumentException("Element is not a sheet placement."),
+        };
+    }
+}

package/src/Revit/Tools/ManageSheets.cs

@@ -1,63 +1,72 @@
-using System.Text.Json;
-using Autodesk.Revit.DB;
-
-namespace RevitBridge.Tools;
-
-internal sealed class ManageSheets : ITool
-{
-    public string Name => "manage_sheets";
-    public string Label => "Manage Sheets";
-    public string Tier => "advanced";
-    public bool Write => true;
-    public string Description => "Create or rename/renumber a drawing sheet. Creation requires name and number; optional titleblock_type_id chooses a loaded titleblock FamilySymbol, otherwise creates a sheet without a titleblock. Update requires sheet_id and accepts name/number. Revit validates unique sheet numbers and valid text; sheet names may repeat; the call rolls back on failure. preview=true commit-validates and rolls back, and new preview sheet IDs are temporary. Use manage_sheet_placements for views/schedules, get_elements for querying sheets, and delete_elements for removal.";
-    public object ParametersSchema => new
-    {
-        type = "object", properties = new
-        {
-            action = new { type = "string", @enum = new[] { "create", "update" } },
-            sheet_id = new { type = "integer", minimum = 1 }, name = new { type = "string", minLength = 1 }, number = new { type = "string", minLength = 1 },
-            titleblock_type_id = new { type = "integer", minimum = 1, description = "Creation only; omitted means no titleblock." }, preview = ModelEditInputs.PreviewSchema,
-        }, required = new[] { "action" },
-    };
-    public object Execute(JsonElement args, ToolContext context)
-    {
-        var doc = context.Document ?? throw new NoActiveDocumentException();
-        string action = JsonArgs.GetString(args, "action") ?? "";
-        if (action is not ("create" or "update")) throw new ArgumentException("action must be create or update.");
-        string? ReadText(string key)
-        {
-            if (!args.TryGetProperty(key, out var value)) return null;
-            if (value.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(value.GetString())) throw new ArgumentException($"{key} must be a nonempty string.");
-            return value.GetString();
-        }
-        string? name = ReadText("name"), number = ReadText("number");
-        if (action == "create" && (name == null || number == null)) throw new ArgumentException("Sheet creation requires name and number.");
-        if (action == "update" && args.TryGetProperty("titleblock_type_id", out _)) throw new ArgumentException("titleblock_type_id is only supported when creating a sheet; use change_element_types on an existing titleblock instance.");
-        return ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(new() { ["action"] = action }, () =>
-        {
-            ViewSheet sheet;
-            object? before = null;
-            if (action == "create")
-            {
-                var typeId = ElementId.InvalidElementId;
-                if (args.TryGetProperty("titleblock_type_id", out _))
-                {
-                    typeId = new ElementId(JsonArgs.GetLong(args, "titleblock_type_id") ?? 0);
-                    var type = doc.GetElement(typeId) as FamilySymbol;
-                    if (type?.Category?.Id.Value != (long)BuiltInCategory.OST_TitleBlocks) throw new ArgumentException("titleblock_type_id must identify a titleblock FamilySymbol.");
-                }
-                sheet = ViewSheet.Create(doc, typeId);
-            }
-            else
-            {
-                sheet = doc.GetElement(new ElementId(JsonArgs.GetLong(args, "sheet_id") ?? 0)) as ViewSheet ?? throw new ArgumentException("sheet_id is not a sheet.");
-                before = Describe(sheet);
-            }
-            if (number != null) sheet.SheetNumber = number;
-            if (name != null) sheet.Name = name;
-            doc.Regenerate();
-            return new() { ["before"] = before, ["sheet"] = Describe(sheet), ["created"] = action == "create", ["id_is_temporary"] = action == "create" && JsonArgs.GetBool(args, "preview", false) };
-        }) }).Payload;
-    }
-    private static object Describe(ViewSheet sheet) => new { id = sheet.Id.Value, unique_id = sheet.UniqueId, name = sheet.Name, number = sheet.SheetNumber, placeholder = sheet.IsPlaceholder };
-}
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class ManageSheets : ITool
+{
+    public string Name => "manage_sheets";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.ProjectOnly;
+    public IReadOnlyList<string> Keywords => new[] { "sheet", "drawing sheet", "sheet number", "rename sheet", "renumber", "titleblock", "new sheet" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Placing views or schedules on a sheet", "tool", "manage_sheet_placements"),
+        new ToolLimit("Revisions and revision clouds", "api", "Revision.Create; RevisionCloud.Create"),
+        new ToolLimit("Deleting sheets", "tool", "delete_elements"),
+    };
+    public string? Verification => "reread";
+    public string Label => "Manage Sheets";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Create or rename/renumber a drawing sheet. Creation requires name and number; optional titleblock_type_id chooses a loaded titleblock FamilySymbol, otherwise creates a sheet without a titleblock. Update requires sheet_id and accepts name/number. Revit validates unique sheet numbers and valid text; sheet names may repeat; the call rolls back on failure. preview=true commit-validates and rolls back, and new preview sheet IDs are temporary. Use manage_sheet_placements for views/schedules, get_elements for querying sheets, and delete_elements for removal.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            action = new { type = "string", @enum = new[] { "create", "update" } },
+            sheet_id = new { type = "integer", minimum = 1 }, name = new { type = "string", minLength = 1 }, number = new { type = "string", minLength = 1 },
+            titleblock_type_id = new { type = "integer", minimum = 1, description = "Creation only; omitted means no titleblock." }, preview = ModelEditInputs.PreviewSchema,
+        }, required = new[] { "action" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        string action = JsonArgs.GetString(args, "action") ?? "";
+        if (action is not ("create" or "update")) throw new ArgumentException("action must be create or update.");
+        string? ReadText(string key)
+        {
+            if (!args.TryGetProperty(key, out var value)) return null;
+            if (value.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(value.GetString())) throw new ArgumentException($"{key} must be a nonempty string.");
+            return value.GetString();
+        }
+        string? name = ReadText("name"), number = ReadText("number");
+        if (action == "create" && (name == null || number == null)) throw new ArgumentException("Sheet creation requires name and number.");
+        if (action == "update" && args.TryGetProperty("titleblock_type_id", out _)) throw new ArgumentException("titleblock_type_id is only supported when creating a sheet; use change_element_types on an existing titleblock instance.");
+        return ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(new() { ["action"] = action }, () =>
+        {
+            ViewSheet sheet;
+            object? before = null;
+            if (action == "create")
+            {
+                var typeId = ElementId.InvalidElementId;
+                if (args.TryGetProperty("titleblock_type_id", out _))
+                {
+                    typeId = new ElementId(JsonArgs.GetLong(args, "titleblock_type_id") ?? 0);
+                    var type = doc.GetElement(typeId) as FamilySymbol;
+                    if (type?.Category?.Id.Value != (long)BuiltInCategory.OST_TitleBlocks) throw new ArgumentException("titleblock_type_id must identify a titleblock FamilySymbol.");
+                }
+                sheet = ViewSheet.Create(doc, typeId);
+            }
+            else
+            {
+                sheet = doc.GetElement(new ElementId(JsonArgs.GetLong(args, "sheet_id") ?? 0)) as ViewSheet ?? throw new ArgumentException("sheet_id is not a sheet.");
+                before = Describe(sheet);
+            }
+            if (number != null) ElementNames.AssignSheetNumber(sheet, number);
+            if (name != null) ElementNames.Assign(sheet, name);
+            doc.Regenerate();
+            return new() { ["before"] = before, ["sheet"] = Describe(sheet), ["created"] = action == "create", ["id_is_temporary"] = action == "create" && JsonArgs.GetBool(args, "preview", false) };
+        }) }).Payload;
+    }
+    private static object Describe(ViewSheet sheet) => new { id = sheet.Id.Value, unique_id = sheet.UniqueId, name = sheet.Name, number = sheet.SheetNumber, placeholder = sheet.IsPlaceholder };
+}