Annotation Guideline

app/AnnotationGuideline.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace Biigle;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * This Model describes the annotation guideline of a Project
+ *
+ * @property int $id
+ */
+class AnnotationGuideline extends Model
+{
+    use HasFactory;
+
+    /**
+     * The attributes that should be casted to native types.
+     *
+     * @var array<string, string>
+     */
+    protected $casts = [
+        'id' => 'int',
+        'project' => 'int',
+        'description' => 'string',
+    ];
+
+    protected $fillable = [
+        'project',
+        'description',
+    ];
+
+    /**
+     * Don't maintain timestamps for this model.
+     *
+     * @var bool
+     */
+    public $timestamps = false;
+
+    /**
+     * The project this guideline belongs to.
+     *
+     * @return \Illuminate\Database\Eloquent\Relations\BelongsTo<Project, $this>
+     */
+    public function project()
+    {
+        return $this->belongsTo(Project::class, 'project');
+    }
+
+    /**
+     * The labels within this guideline.
+     *
+     * @return \Illuminate\Database\Eloquent\Relations\HasMany<AnnotationGuidelineLabel, $this>
+     */
+    public function guidelineLabels()
+    {
+        return $this->hasMany(AnnotationGuidelineLabel::class, 'annotation_guideline');
+    }
+}

app/AnnotationGuidelineLabel.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace Biigle;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * Model for labels within an annotation guideline.
+ *
+ * @property int $id
+ */
+class AnnotationGuidelineLabel extends Model
+{
+    use HasFactory;
+
+    /**
+     * The attributes that should be casted to native types.
+     *
+     * @var array<string, string>
+     */
+    protected $casts = [
+        'annotation_guideline' => 'int',
+        'label' => 'int',
+        'shape' => 'int',
+        'description' => 'string',
+        'reference_image' => 'boolean',
+    ];
+
+    /**
+     * The attributes that are mass assignable.
+     *
+     * @var list<string>
+     */
+    protected $fillable = [
+        'annotation_guideline',
+        'label',
+        'shape',
+        'description',
+        'reference_image',
+    ];
+    /**
+     * Don't maintain timestamps for this model.
+     *
+     * @var bool
+     */
+    public $timestamps = false;
+
+    /**
+     * The labels that have a guideline for their annotation
+     *
+     * @return \Illuminate\Database\Eloquent\Relations\BelongsTo<Label, $this>
+     */
+    public function label()
+    {
+        return $this->belongsTo(Label::class, 'label');
+    }
+}

app/Http/Controllers/Api/Projects/AnnotationGuidelineController.php

@@ -0,0 +1,110 @@
+<?php
+
+namespace Biigle\Http\Controllers\Api\Projects;
+
+use Biigle\AnnotationGuideline;
+use Biigle\Http\Controllers\Api\Controller;
+use Biigle\Project;
+use Illuminate\Http\Request;
+use Storage;
+
+class AnnotationGuidelineController extends Controller
+{
+    /**
+     * Get the annotation guideline for the given project and the associated labels
+     *
+     * @api {get} projects/:pid/annotation-guideline Get the annotation guideline for the given project
+     * @apiGroup Projects
+     * @apiName AnnotationGuideline
+     * @apiParam {Number} id The Project ID
+     * @apiPermission projectAdmin
+     * @apiDescription Returns the annotation guideline and the associated labels
+     *
+     * @apiSuccessExample {json} Success response:
+     * {"annotation_guideline":[{
+     *    "id":1,
+     *    "project":2,
+     *    "description":"guideline description"
+     *  }],
+     *  "annotation_guideline_labels" : [{
+     *      "annotation_guideline": 1,
+     *      "label":4,
+     *      "shape":7,
+     *      "description":"description of a label",
+     *      "label":
+     *        {
+     *          "id":4,
+     *          "name":"something else",
+     *        },
+     *  }]}
+     *
+     */
+    public function index($id)
+    {
+        $project = Project::findOrFail($id);
+        $this->authorize('update', $project);
+        $guideline = AnnotationGuideline::where(['project'=> $id])
+            ->firstOrFail();
+        $guidelineLabels = $guideline
+            ->guidelineLabels()
+            ->select()
+            ->with('label')
+            ->get();
+        return ['annotation_guideline' => $guideline, 'annotation_guideline_labels' => $guidelineLabels];
+
+    }
+
+    /**
+     * Update the annotation guideline for the given project
+     *
+     * @api {post} projects/:pid/annotation-guideline Update the annotation guideline for the given project
+     * @apiGroup Projects
+     * @apiName AnnotationGuideline
+     * @apiParam {Number} id The Project ID
+     * @apiParam {String} description A description on how to annotate the guideline
+     * @apiPermission projectAdmin
+     * @apiDescription Edit the annotation guideline associated with the given ID
+     *
+     * @param int $id Project ID
+     */
+    public function update(Request $request, int $id)
+    {
+        $request->validate([
+            'description' => 'nullable|string|min:1',
+        ]);
+
+        $project = Project::findOrFail($id);
+        $this->authorize('update', $project);
+
+        AnnotationGuideline::updateOrCreate(
+            ['project' => $project->id],
+            ['description' =>  $request->description]
+        );
+
+    }
+
+    /**
+     * Delete the annotation guideline for the given project
+     *
+     * @api {delete} projects/:pid/annotation-guideline Delete the annotation guideline for the given project
+     * @apiGroup Projects
+     * @apiName AnnotationGuideline
+     * @apiParam {Number} id The Project ID
+     * @apiPermission projectAdmin
+     * @apiDescription Delete the annotation guideline associated with the given ID
+     */
+    public function delete(Request $request)
+    {
+        $project = Project::findOrFail($request->id);
+        $this->authorize('update', $project);
+        $annotationGuideline = AnnotationGuideline::where(['project'=> $project->id])->firstOrFail();
+        $annotationGuideline->delete();
+
+        //Cleanup the directory
+        $disk = Storage::disk(config('projects.annotation_guideline_storage_disk'));
+        $url = "$project->id/";
+        if ($disk->exists($url)) {
+            $disk->deleteDirectory($url);
+        }
+    }
+}

app/Http/Controllers/Api/Projects/AnnotationGuidelineLabelController.php

@@ -0,0 +1,128 @@
+<?php
+
+namespace Biigle\Http\Controllers\Api\Projects;
+
+use Biigle\AnnotationGuideline;
+use Biigle\AnnotationGuidelineLabel;
+use Biigle\Http\Controllers\Api\Controller;
+use Biigle\Http\Requests\StoreAnnotationGuidelineLabel;
+use Biigle\Label;
+use Biigle\Project;
+use Biigle\Shape;
+use Illuminate\Http\Request;
+use Storage;
+
+class AnnotationGuidelineLabelController extends Controller
+{
+    /**
+     * Update the label within an annotation guideline.
+     * @api {post} projects/:id/annotation-guideline-label Update the guideline for labels within an annotation guideline
+     * @apiGroup Projects
+     * @apiName UpdateAnnotationGuidelineLabel
+     * @apiPermission projectAdmin
+     *
+     * @apiParam {Integer} id THe ID of the project for the annotation guideline for the labels
+     * @apiParam {Integer} label The ID for the label for the annotation guideline
+     * @apiParam {Integer} shape (optional) The ID for the preferred shape for the label in the annotation guideline
+     * @apiParam {String} description (optional) A description of the label
+     * @apiParam {File} reference_image (optional) The reference image for the label
+     *
+     */
+    public function update(StoreAnnotationGuidelineLabel $request)
+    {
+
+        $projectId = $request->project->id;
+        $annotationGuideline = AnnotationGuideline::where(['project' => $projectId])->firstOrFail();
+        $validated = $request->validated();
+
+        $labelId = $validated['label'];
+        $label = Label::findOrFail($labelId);
+
+        $shapeId = $validated['shape'] ?? null;
+        if (!is_null($shapeId)) {
+            $shapeId = Shape::findOrFail($shapeId)->id;
+        }
+
+        $description = $validated['description'] ?? null;
+        $referenceImage = $validated['reference_image'] ?? null;
+
+        $disk = Storage::disk(config('projects.annotation_guideline_storage_disk'));
+
+        $hasReferenceImage = !is_null($referenceImage);
+        if ($hasReferenceImage) {
+            $disk->putFileAs("$projectId", $referenceImage, "$label->id.jpg");
+        }
+
+        //If image already exists, avoid problems
+        $imageExists = $disk->exists("$projectId/$label->id.jpg");
+        AnnotationGuidelineLabel::updateOrCreate(
+            [
+                'annotation_guideline' => $annotationGuideline->id,
+                'label' => $label->id,
+            ],
+            [
+                'shape' => $shapeId,
+                'description' => $description,
+                'reference_image' => $imageExists,
+            ]
+        );
+    }
+
+    /**
+     * Delete a label from a guideline.
+     *
+     * @api {delete} projects/:id/annotation-guideline-labels/delete-image Delete a reference image
+     * @apiGroup Projects
+     * @apiName DeleteReferenceImage
+     * @apiPermission projectAdmin
+     *
+     * @apiParam {Integer} id The ID of the project for the annotation guideline for the labels
+     *
+     */
+    public function delete(Request $request)
+    {
+        $project = Project::findOrFail($request->id);
+        $label = Label::findOrFail($request->label);
+        $annotationGuideline = AnnotationGuideline::where(['project' => $project->id])->firstOrFail();
+        $annotationGuidelineLabel = $annotationGuideline->guidelineLabels()->where(['label' => $label->id])->firstOrFail();
+
+        $this->authorize('update', $project);
+
+        $annotationGuidelineLabel->delete();
+
+        $disk = Storage::disk(config('projects.annotation_guideline_storage_disk'));
+        $url = "$project->id/$label->id.jpg";
+        if ($disk->exists($url)) {
+            $disk->delete($url);
+        }
+    }
+
+    /**
+     * Delete a reference image.
+     *
+     * @api {delete} projects/:id/annotation-guideline-labels/delete-image Delete a reference image
+     * @apiGroup Projects
+     * @apiName DeleteReferenceImage
+     * @apiPermission projectAdmin
+     *
+     * @apiParam {Integer} id The ID of the project for the annotation guideline for the labels
+     *
+     */
+    public function deleteReferenceImage(Request $request)
+    {
+        $project = Project::findOrFail($request->id);
+        $label = Label::findOrFail($request->label);
+        $annotationGuideline = AnnotationGuideline::where(['project' => $project->id])->firstOrFail();
+        $annotationGuidelineLabel = $annotationGuideline->guidelineLabels()->where(['label' => $label->id])->firstOrFail();
+
+        $this->authorize('update', $project);
+
+        $annotationGuidelineLabel->update(['reference_image' => false]);
+
+        $disk = Storage::disk(config('projects.annotation_guideline_storage_disk'));
+        $url = "$project->id/$label->id.jpg";
+        if ($disk->exists($url)) {
+            $disk->delete($url);
+        }
+    }
+}