Markdown documentation for tasks/projects

CHANGELOG.md

@@ -7,7 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## \[Unreleased]
 ### Added
-- TDB
+- Now CVAT supports project/task markdown description with additional assets
+(png, jpeg, gif, webp images and pdf files) (<https://github.com/opencv/cvat/pull/6191>)
 
 ### Changed
 - TDB

cvat-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cvat-core",
-  "version": "9.1.3",
+  "version": "9.2.0",
   "description": "Part of Computer Vision Tool which presents an interface for client-side integration",
   "main": "src/api.ts",
   "scripts": {

cvat-core/src/api-implementation.ts

@@ -25,6 +25,8 @@ import Project from './project';
 import CloudStorage from './cloud-storage';
 import Organization from './organization';
 import Webhook from './webhook';
+import { ArgumentError } from './exceptions';
+import { SerializedAsset } from './server-response-types';
 
 export default function implementAPI(cvat) {
     cvat.plugins.list.implementation = PluginRegistry.list;
@@ -133,6 +135,15 @@ export default function implementAPI(cvat) {
         return result;
     };
 
+    cvat.assets.create.implementation = async (file: File, guideId: number): Promise<SerializedAsset> => {
+        if (!(file instanceof File)) {
+            throw new ArgumentError('Assets expect a file');
+        }
+
+        const result = await serverProxy.assets.create(file, guideId);
+        return result;
+    };
+
     cvat.users.get.implementation = async (filter) => {
         checkFilter(filter, {
             id: isInteger,

cvat-core/src/api.ts

@@ -3,11 +3,6 @@
 //
 // SPDX-License-Identifier: MIT
 
-/**
- * External API which should be used by for development
- * @module API
- */
-
 import PluginRegistry from './plugins';
 import loggerStorage from './logger-storage';
 import { EventLogger } from './log';
@@ -25,6 +20,7 @@ import { FrameData } from './frames';
 import CloudStorage from './cloud-storage';
 import Organization from './organization';
 import Webhook from './webhook';
+import AnnotationGuide from './guide';
 
 import * as enums from './enums';
 
@@ -147,6 +143,12 @@ function build() {
                 return result;
             },
         },
+        assets: {
+            async create(file: File, guideId: number) {
+                const result = await PluginRegistry.apiWrapper(cvat.assets.create, file, guideId);
+                return result;
+            },
+        },
         jobs: {
             async get(filter = {}) {
                 const result = await PluginRegistry.apiWrapper(cvat.jobs.get, filter);
@@ -287,6 +289,7 @@ function build() {
             CloudStorage,
             Organization,
             Webhook,
+            AnnotationGuide,
         },
     };
 

cvat-core/src/guide.ts

@@ -0,0 +1,92 @@
+// Copyright (C) 2023 CVAT.ai Corporation
+//
+// SPDX-License-Identifier: MIT
+
+import { SerializedGuide } from './server-response-types';
+import { ArgumentError, DataError } from './exceptions';
+import PluginRegistry from './plugins';
+import serverProxy from './server-proxy';
+
+class AnnotationGuide {
+    #id: AnnotationGuide['id'];
+    #taskId: AnnotationGuide['taskId'];
+    #projectId: AnnotationGuide['projectId'];
+    #createdDate?: AnnotationGuide['createdDate'];
+    #updatedDate?: AnnotationGuide['updatedDate'];
+    #markdown: AnnotationGuide['markdown'];
+
+    constructor(initialData: Partial<SerializedGuide>) {
+        this.#id = initialData.id;
+        this.#taskId = initialData.task_id || null;
+        this.#projectId = initialData.project_id || null;
+        this.#createdDate = initialData.created_date;
+        this.#updatedDate = initialData.updated_date;
+        this.#markdown = initialData.markdown || '';
+    }
+
+    public get id(): number | undefined {
+        return this.#id;
+    }
+
+    public get taskId(): number | null {
+        return this.#taskId;
+    }
+
+    public get projectId(): number | null {
+        return this.#projectId;
+    }
+
+    public get createdDate(): string | undefined {
+        return this.#createdDate;
+    }
+
+    public get updatedDate(): string | undefined {
+        return this.#updatedDate;
+    }
+
+    public get markdown(): string {
+        return this.#markdown;
+    }
+
+    public set markdown(value: string) {
+        if (typeof value !== 'string') {
+            throw new ArgumentError(`Markdown value must be a string, ${typeof value} received`);
+        }
+        this.#markdown = value;
+    }
+
+    async save(): Promise<AnnotationGuide> {
+        const result = await PluginRegistry.apiWrapper.call(this, AnnotationGuide.prototype.save);
+        return result;
+    }
+}
+
+Object.defineProperties(AnnotationGuide.prototype.save, {
+    implementation: {
+        writable: false,
+        enumerable: false,
+        value: async function implementation(this: AnnotationGuide) {
+            if (Number.isInteger(this.id)) {
+                const result = await serverProxy.guides.update(this.id, { markdown: this.markdown });
+                return new AnnotationGuide(result);
+            }
+
+            if (this.projectId === null && this.taskId === null) {
+                throw new DataError('One of projectId or taskId must be specified for a guide');
+            }
+
+            if (this.projectId !== null && this.taskId !== null) {
+                throw new DataError('Both projectId and taskId must not be presented for a guide');
+            }
+
+            const result = await serverProxy.guides.create({
+                task_id: this.taskId,
+                project_id: this.projectId,
+                markdown: this.markdown,
+            });
+            return new AnnotationGuide(result);
+        },
+    },
+});
+
+export default AnnotationGuide;

cvat-core/src/project-implementation.ts

@@ -10,6 +10,7 @@ import Project from './project';
 import { exportDataset, importDataset } from './annotations';
 import { SerializedLabel } from './server-response-types';
 import { Label } from './labels';
+import AnnotationGuide from './guide';
 
 export default function implementProject(projectClass) {
     projectClass.prototype.save.implementation = async function () {
@@ -125,5 +126,14 @@ export default function implementProject(projectClass) {
         return result;
     };
 
+    projectClass.prototype.guide.implementation = async function guide() {
+        if (this.guideId === null) {
+            return null;
+        }
+
+        const result = await serverProxy.guides.get(this.guideId);
+        return new AnnotationGuide(result);
+    };
+
     return projectClass;
 }

cvat-core/src/project.ts

@@ -12,13 +12,15 @@ import { ArgumentError } from './exceptions';
 import { Label } from './labels';
 import User from './user';
 import { FieldUpdateTrigger } from './common';
+import AnnotationGuide from './guide';
 
 export default class Project {
     public readonly id: number;
     public name: string;
     public assignee: User;
     public bugTracker: string;
     public readonly status: ProjectStatus;
+    public readonly guideId: number | null;
     public readonly organization: string | null;
     public readonly owner: User;
     public readonly createdDate: string;
@@ -39,6 +41,7 @@ export default class Project {
             name: undefined,
             status: undefined,
             assignee: undefined,
+            guide_id: undefined,
             organization: undefined,
             owner: undefined,
             bug_tracker: undefined,
@@ -98,6 +101,9 @@ export default class Project {
                 owner: {
                     get: () => data.owner,
                 },
+                guideId: {
+                    get: () => data.guide_id,
+                },
                 organization: {
                     get: () => data.organization,
                 },
@@ -230,6 +236,11 @@ export default class Project {
         const result = await PluginRegistry.apiWrapper.call(this, Project.restore, storage, file);
         return result;
     }
+
+    async guide(): Promise<AnnotationGuide | null> {
+        const result = await PluginRegistry.apiWrapper.call(this, Project.prototype.guide);
+        return result;
+    }
 }
 
 Object.defineProperties(

cvat-core/src/server-proxy.ts

@@ -11,7 +11,7 @@ import {
     SerializedLabel, SerializedAnnotationFormats, ProjectsFilter,
     SerializedProject, SerializedTask, TasksFilter, SerializedUser,
     SerializedAbout, SerializedRemoteFile, SerializedUserAgreement,
-    SerializedRegister, JobsFilter, SerializedJob,
+    SerializedRegister, JobsFilter, SerializedJob, SerializedGuide, SerializedAsset,
 } from 'server-response-types';
 import { Storage } from './storage';
 import { StorageLocation, WebhookSourceType } from './enums';
@@ -2167,6 +2167,57 @@ async function receiveWebhookEvents(type: WebhookSourceType): Promise<string[]>
     }
 }
 
+async function getGuide(id: number, params = {}): Promise<SerializedGuide> {
+    const { backendAPI } = config;
+
+    try {
+        const response = await Axios.get(`${backendAPI}/guides/${id}`, { params });
+        return response.data;
+    } catch (errorData) {
+        throw generateError(errorData);
+    }
+}
+
+async function createGuide(data: Partial<SerializedGuide>): Promise<SerializedGuide> {
+    const { backendAPI } = config;
+
+    try {
+        const response = await Axios.post(`${backendAPI}/guides`, data);
+        return response.data;
+    } catch (errorData) {
+        throw generateError(errorData);
+    }
+}
+
+async function updateGuide(id: number, data: Partial<SerializedGuide>): Promise<SerializedGuide> {
+    const { backendAPI } = config;
+
+    try {
+        const response = await Axios.patch(`${backendAPI}/guides/${id}`, data);
+        return response.data;
+    } catch (errorData) {
+        throw generateError(errorData);
+    }
+}
+
+async function createAsset(file: File, guideId: number): Promise<SerializedAsset> {
+    const { backendAPI } = config;
+    const form = new FormData();
+    form.append('file', file);
+    form.append('guide_id', guideId);
+
+    try {
+        const response = await Axios.post(`${backendAPI}/assets`, form, {
+            headers: {
+                'Content-Type': 'multipart/form-data',
+            },
+        });
+        return response.data;
+    } catch (errorData) {
+        throw generateError(errorData);
+    }
+}
+
 export default Object.freeze({
     server: Object.freeze({
         setAuthData,
@@ -2310,4 +2361,14 @@ export default Object.freeze({
         ping: pingWebhook,
         events: receiveWebhookEvents,
     }),
+
+    guides: Object.freeze({
+        get: getGuide,
+        create: createGuide,
+        update: updateGuide,
+    }),
+
+    assets: Object.freeze({
+        create: createAsset,
+    }),
 });

cvat-core/src/server-response-types.ts

@@ -61,6 +61,7 @@ export interface SerializedProject {
     dimension: DimensionType;
     name: string;
     organization: number | null;
+    guide_id: number | null;
     owner: SerializedUser;
     source_storage: { id: number; location: 'local' | 'cloud'; cloud_storage_id: null };
     target_storage: { id: number; location: 'local' | 'cloud'; cloud_storage_id: null };
@@ -94,6 +95,7 @@ export interface SerializedTask {
     overlap: number | null;
     owner: SerializedUser;
     project_id: number | null;
+    guide_id: number | null;
     segment_size: number;
     size: number;
     source_storage: { id: number; location: 'local' | 'cloud'; cloud_storage_id: null };
@@ -115,10 +117,11 @@ export interface SerializedJob {
     labels: { count: number; url: string };
     mode: TaskMode;
     project_id: number | null;
+    guide_id: number | null;
     stage: JobStage;
     state: JobState;
-    startFrame: number;
-    stopFrame: number;
+    start_frame: number;
+    stop_frame: number;
     task_id: number;
     updated_date: string;
     url: string;
@@ -174,3 +177,21 @@ export interface SerializedRegister {
     last_name: string;
     username: string;
 }
+
+export interface SerializedGuide {
+    id?: number;
+    task_id: number | null;
+    project_id: number | null;
+    owner: SerializedUser;
+    created_date: string;
+    updated_date: string;
+    markdown: string;
+}
+
+export interface SerializedAsset {
+    uuid?: string;
+    guide?: number;
+    filename: string;
+    created_date: string;
+    owner: SerializedUser;
+}