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 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 @@
  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 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 @@
  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 @@
  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 { 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 @@
  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 { 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 @@
  name: undefined,
  status: undefined,
  assignee: undefined,
+ guide_id: undefined,
  organization: undefined,
  owner: undefined,
  bug_tracker: undefined,
@@ -98,6 +101,9 @@
  owner: {
  get: () => data.owner,
  },
+ guideId: {
+ get: () => data.guide_id,
+ },
  organization: {
  get: () => data.organization,
  },
@@ -230,6 +236,11 @@
  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 @@
  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 getGuide(id: number): Promise<SerializedGuide> {
+ const { backendAPI } = config;
+
+ try {
+ const response = await Axios.get(`${backendAPI}/guides/${id}`);
+ 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 @@
  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;
+}