Markdown documentation for tasks/projects

cvat-core/src/api-implementation.ts

@@ -25,6 +25,9 @@ import Project from './project';
 import CloudStorage from './cloud-storage';
 import Organization from './organization';
 import Webhook from './webhook';
+import { ArgumentError } from './exceptions';
+import AnnotationGuide from './guide';
+import { SerializedAsset } from 'server-response-types';
 
 export default function implementAPI(cvat) {
  cvat.plugins.list.implementation = PluginRegistry.list;
@@ -133,6 +136,25 @@ export default function implementAPI(cvat) {
  return result;
  };
 
+ cvat.guides.get.implementation = async (filter: { id: number }) => {
+ if (!('id' in filter)) {
+ throw new ArgumentError('Guide id was not provided');
+ }
+ checkFilter(filter, { id: isInteger });
+
+ const result = await serverProxy.guides.get(filter.id);
+ return new AnnotationGuide(result);
+ };
+
+ cvat.assets.create.implementation = async (file: File): Promise<SerializedAsset> => {
+ if (!(file instanceof File)) {
+ throw new ArgumentError('Assets expect a file');
+ }
+
+ const result = await serverProxy.assets.create(file);
+ 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,18 @@ function build() {
  return result;
  },
  },
+ guides: {
+ async get(filter: { id: number }) {
+ const result = await PluginRegistry.apiWrapper(cvat.guides.get, filter);
+ return result;
+ },
+ },
+ assets: {
+ async create(file: File) {
+ const result = await PluginRegistry.apiWrapper(cvat.assets.create, file);
+ return result;
+ },
+ },
  jobs: {
  async get(filter = {}) {
  const result = await PluginRegistry.apiWrapper(cvat.jobs.get, filter);
@@ -281,6 +289,7 @@ function build() {
  CloudStorage,
  Organization,
  Webhook,
+ AnnotationGuide,
  },
  };
 

cvat-core/src/guide.ts

@@ -0,0 +1,103 @@
+// Copyright (C) 2023 CVAT.ai Corporation
+//
+// SPDX-License-Identifier: MIT
+
+import User from './user';
+import { SerializedGuide } from './server-response-types';
+import { ArgumentError, DataError } from './exceptions';
+import PluginRegistry from './plugins';
+import serverProxy from './server-proxy';
+
+class AnnotationGuide {
+ public readonly id?: number;
+ public readonly taskId: number;
+ public readonly projectId: number;
+ public readonly owner?: User;
+ public readonly createdDate?: string;
+ public readonly updatedDate?: string;
+ public markdown: string;
+
+ constructor(initialData: Partial<SerializedGuide>) {
+ const data = {
+ id: undefined,
+ task_id: null,
+ project_id: null,
+ owner: undefined,
+ created_date: undefined,
+ updated_date: undefined,
+ markdown: '',
+ };
+
+ for (const property in data) {
+ if (Object.prototype.hasOwnProperty.call(data, property) && property in initialData) {
+ data[property] = initialData[property];
+ }
+ }
+ if (data.owner) data.owner = new User(data.owner);
+
+ Object.defineProperties(this, Object.freeze({
+ id: {
+ get: () => data.id,
+ },
+ taskId: {
+ get: () => data.task_id,
+ },
+ projectId: {
+ get: () => data.project_id,
+ },
+ owner: {
+ get: () => data.owner,
+ },
+ createdDate: {
+ get: () => data.created_date,
+ },
+ updatedData: {
+ get: () => data.updated_date,
+ },
+ markdown: {
+ get: () => data.markdown,
+ set: (value: string) => {
+ if (typeof value !== 'string') {
+ throw new ArgumentError(`Markdown value must be a string, ${typeof value} received`);
+ }
+ data.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 presented 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.ts

@@ -19,6 +19,7 @@ export default class Project {
  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 +40,7 @@ export default class Project {
  name: undefined,
  status: undefined,
  assignee: undefined,
+ guide_id: undefined,
  organization: undefined,
  owner: undefined,
  bug_tracker: undefined,
@@ -98,6 +100,9 @@ export default class Project {
  owner: {
  get: () => data.owner,
  },
+ guideId: {
+ get: () => data.guide_id,
+ },
  organization: {
  get: () => data.organization,
  },

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';
@@ -2146,6 +2146,56 @@ async function receiveWebhookEvents(type: WebhookSourceType): Promise<string[]>
  }
 }
 
+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): Promise<SerializedAsset> {
+ const { backendAPI } = config;
+ const form = new FormData();
+ form.append('file', file);
+
+ 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,
@@ -2289,4 +2339,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;
+}